<HTML>
<HEAD>
<TITLE> FRMDIFF User's Guide </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>FRMDIFF User's Guide</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#FRMDIFF User's Guide">FRMDIFF User's Guide</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#Summary">Summary</A>
      <A HREF="#If You Are in a Hurry">If You Are in a Hurry</A>
         <A HREF="#To Check if Two CK Files Provide Identical Data">To Check if Two CK Files Provide Identical Data</A>
         <A HREF="#To Assess Difference Between Two CK Files">To Assess Difference Between Two CK Files</A>
         <A HREF="#To Sample Quaternions from a CK File">To Sample Quaternions from a CK File</A>
         <A HREF="#To Compute Transformation Between Two Frames">To Compute Transformation Between Two Frames</A>
      <A HREF="#Usage">Usage</A>
      <A HREF="#Options">Options</A>
   <A HREF="#Inputs">Inputs</A>
      <A HREF="#Kernel Files">Kernel Files</A>
         <A HREF="#Primary Kernel Files">Primary Kernel Files</A>
         <A HREF="#Additional Kernel Files">Additional Kernel Files</A>
      <A HREF="#Comparison Runs vs. Sampling Runs">Comparison Runs vs. Sampling Runs</A>
      <A HREF="#Runs with Two, One, and No Primary Kernel File(s)">Runs with Two, One, and No Primary Kernel File(s)</A>
         <A HREF="#Runs with Two Primary Kernel Files">Runs with Two Primary Kernel Files</A>
         <A HREF="#Runs with One Primary Kernel File">Runs with One Primary Kernel File</A>
         <A HREF="#Runs Without Primary Kernel Files">Runs Without Primary Kernel Files</A>
      <A HREF="#``From'', ``To'', and ``Coverage'' Frames">``From'', ``To'', and ``Coverage'' Frames</A>
         <A HREF="#``From'' Frames">``From'' Frames</A>
         <A HREF="#``To'' Frames">``To'' Frames</A>
         <A HREF="#``Coverage'' Frames">``Coverage'' Frames</A>
      <A HREF="#Times for Comparison/Sampling">Times for Comparison/Sampling</A>
         <A HREF="#Coverage Window">Coverage Window</A>
         <A HREF="#Times within Coverage Window">Times within Coverage Window</A>
      <A HREF="#Angular Velocities">Angular Velocities</A>
   <A HREF="#Output">Output</A>
      <A HREF="#Overview of Report Types">Overview of Report Types</A>
         <A HREF="#Time Tag Format for ``dump*'' Reports">Time Tag Format for ``dump*'' Reports</A>
         <A HREF="#Angle Units for ``dumpaa'' and ``dumpea'' Reports">Angle Units for ``dumpaa'' and ``dumpea'' Reports</A>
      <A HREF="#Report Header">Report Header</A>
         <A HREF="#Report Header for Comparing Two Orientations">Report Header for Comparing Two Orientations</A>
         <A HREF="#Report Header for Coverage/Gaps for Two Orientations">Report Header for Coverage/Gaps for Two Orientations</A>
         <A HREF="#Report Header for Sampling an Orientation">Report Header for Sampling an Orientation</A>
         <A HREF="#Report Header for Coverage/Gaps for An Orientation">Report Header for Coverage/Gaps for An Orientation</A>
      <A HREF="#Report Formats">Report Formats</A>
         <A HREF="#Basic Report (no ``-t'' or ``-t basic'')">Basic Report (no ``-t'' or ``-t basic'')</A>
         <A HREF="#Statistics Report (``-t stats'')">Statistics Report (``-t stats'')</A>
         <A HREF="#Angle and Axis Dump Report (``-t dumpaa'')">Angle and Axis Dump Report (``-t dumpaa'')</A>
         <A HREF="#Matrix Dump Report (``-t dumpm'')">Matrix Dump Report (``-t dumpm'')</A>
         <A HREF="#SPICE-Style Quaternion Dump Report (``-t dumpqs'')">SPICE-Style Quaternion Dump Report (``-t dumpqs'')</A>
         <A HREF="#``Other''-Style Quaternion Dump Report (``-t dumpqo'')">``Other''-Style Quaternion Dump Report (``-t dumpqo'')</A>
         <A HREF="#Euler Angles Dump Report (``-t dumpea'')">Euler Angles Dump Report (``-t dumpea'')</A>
         <A HREF="#Coverage Intervals Dump Report (``-t dumpc''):">Coverage Intervals Dump Report (``-t dumpc''):</A>
         <A HREF="#Coverage Gaps Dump Report (``-t dumpg'')">Coverage Gaps Dump Report (``-t dumpg'')</A>
   <A HREF="#Examples">Examples</A>
      <A HREF="#Checking if Two CKs Provide the Same Orientation">Checking if Two CKs Provide the Same Orientation</A>
      <A HREF="#Comparing Predicted and Reconstructed CKs">Comparing Predicted and Reconstructed CKs</A>
      <A HREF="#Comparing Orientations from a CK Read Using Different SCLKs">Comparing Orientations from a CK Read Using Different SCLKs</A>
      <A HREF="#Comparing Binary and Text PCKs">Comparing Binary and Text PCKs</A>
      <A HREF="#Comparing Two Text PCKs">Comparing Two Text PCKs</A>
      <A HREF="#Sampling Orientation from a CK">Sampling Orientation from a CK</A>
      <A HREF="#Sampling Orientation of a Built-in Frame">Sampling Orientation of a Built-in Frame</A>
      <A HREF="#Sampling Orientation of a Dynamic Frame">Sampling Orientation of a Dynamic Frame</A>
      <A HREF="#Displaying Overlap in Coverage between Two CKs">Displaying Overlap in Coverage between Two CKs</A>
      <A HREF="#Displaying Gaps in a CK File">Displaying Gaps in a CK File</A>
   <A HREF="#Miscellaneous Things to Consider">Miscellaneous Things to Consider</A>
      <A HREF="#``Apples vs. Oranges''">``Apples vs. Oranges''</A>
      <A HREF="#Using Euler Angles for Small Rotation Differences">Using Euler Angles for Small Rotation Differences</A>
      <A HREF="#Single Epoch">Single Epoch</A>
   <A HREF="#References">References</A>
   <A HREF="#Acronyms">Acronyms</A>
   <A HREF="#Appendix 1: Comparison, Sampling and Report Quantity Algorithms">Appendix 1: Comparison, Sampling and Report Quantity Algorithms</A>
      <A HREF="#Computing Rotation and Angular Velocity Difference">Computing Rotation and Angular Velocity Difference</A>
      <A HREF="#Sampling Rotation and Angular Velocity">Sampling Rotation and Angular Velocity</A>
      <A HREF="#Converting Rotation to Angle/Axis">Converting Rotation to Angle/Axis</A>
      <A HREF="#Converting Rotation to SPICE-Style Quaternion">Converting Rotation to SPICE-Style Quaternion</A>
      <A HREF="#Converting Rotation to ``Other''-Style quaternion">Converting Rotation to ``Other''-Style quaternion</A>
      <A HREF="#Converting Rotation to Euler Angles">Converting Rotation to Euler Angles</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="FRMDIFF User's Guide"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> FRMDIFF User's Guide
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2009 FEB 10 by B. V. Semenov.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   FRMDIFF is a program that samples orientation of a reference frame known
   to SPICE or computes differences between orientations of two reference
   frames known to SPICE, and either displays this orientation or these
   differences, or shows statistics about it or them.
<P>
 
<BR><BR>
<A NAME="Summary"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   FRMDIFF provides means for sampling orientation of a single reference
   frame, or for comparing orientations of two reference frames known to
   SPICE and supported by data from SPICE kernels.
<P>
 
   To sample orientation of a single frame the program computes a set of
   transformations from one frame (the ``from'' frame) to another frame
   (the ``to'' frame) over an interval of time with fixed or variable time
   step, using a given set of kernel files. Then, depending on the
   requested type of output report, it prints to the screen a table
   containing these transformations expressed as total rotation angles and
   axes, quaternions, matrices or Euler angles and angular velocities, or
   only magnitude of the maximum rotation and angular velocity, or results
   of a simple statistical analysis of rotations.
<P>
 
   To compare orientations of two frames the program computes a set of
   transformations from one frame (the ``from'' frame) to another frame
   (the ``to'' frame) over an interval of time with a fixed or variable
   time step using one set of kernels, computes a set of transformations
   for the same or a different ``from''-``to'' frame combination at the
   same times using the same or a different set of kernels, and then
   computes the difference in rotation and angular velocity between the
   corresponding transformations. Depending on the requested type of output
   report the program prints to the screen only maximum differences in
   rotation and angular velocity, or a complete table of rotation and
   angular velocity differences expressed as total rotation angles and
   axes, matrices, quaternions, or Euler angles, or results of a simple
   statistical analysis of the rotation differences.
<P>
 
<BR><BR>
<A NAME="If You Are in a Hurry"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> If You Are in a Hurry
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   This section shows four very common FRMDIFF usage scenarios with just
   enough explanations to get you going. An extensive set of detailed
   examples is provided at the end of this User's Guide.
<P>
 
<BR><BR>
<A NAME="To Check if Two CK Files Provide Identical Data"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> To Check if Two CK Files Provide Identical Data
</H3><P><BR><BR>
   To check if two CK files containing orientation for the same structure
   with respect to the same reference frame provide identical data, run
   FRMDIFF as follows:
<P>
 
<PRE>
   % frmdiff -k &lt;lsk&gt; &lt;sclk&gt; &lt;fk&gt; -s &lt;step&gt; &lt;ck1&gt; &lt;ck2&gt;
</PRE>
   where ``&lt;lsk&gt;'', ``&lt;sclk&gt;'', ``&lt;fk&gt;'', ``&lt;ck1&gt;''
   and ``&lt;ck2&gt;'' are the names of LSK, SCLK, FK, and two CK files
   (all five are required), and ``step'' is the time step, in seconds. If
   the maximum rotation angle in the output is zero (or close to zero,
   accounting for round off), then the CKs contain the same data. To
   include angular velocities in comparison, add ``-a yes'' before ``-s'',
   like this:
<P>
 
<PRE>
   % frmdiff -k &lt;lsk&gt; &lt;sclk&gt; &lt;fk&gt; -a yes -s &lt;step&gt; &lt;ck1&gt; &lt;ck2&gt;
</PRE>
<BR><BR>
<A NAME="To Assess Difference Between Two CK Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> To Assess Difference Between Two CK Files
</H3><P><BR><BR>
   To assess the difference between two CK files containing orientation for
   the same structure with respect to the same reference frame as a
   function of time, run FRMDIFF as follows:
<P>
 
<PRE>
   % frmdiff -k &lt;lsk&gt; &lt;sclk&gt; &lt;fk&gt; -t dumpaa -s &lt;step&gt; &lt;ck1&gt; &lt;ck2&gt;
</PRE>
   where ``&lt;lsk&gt;'', ``&lt;sclk&gt;'', ``&lt;fk&gt;'', ``&lt;ck1&gt;''
   and ``&lt;ck2&gt;'' are the names of LSK, SCLK, FK, and two CK files
   (all five are required); ``-t dumpaa'' sets the output format to the
   rotation angle and axis dump; and ``step'' is the time step, in seconds.
   The program's output, which can be rather lengthy, can be re-directed to
   a file using the ``&gt;'' pipe. Using the data captured in the file the
   total rotation angle (column 2) can be plotted against TDB seconds
   (column 1) to analyze the difference. To print output time tags as UTC
   in ISO date format instead of TDB seconds, add
<P>
 
<PRE>
   -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
</PRE>
   before ``-k''. To use the Euler angle dump output instead of the
   rotation angle and axis dump output, replace ``dumpaa'' with ``dumpea''.
   To include angular velocities in the comparison, add ``-a yes'' before
   ``-s'', like this (the command line below is wrapped to fit the page
   width):
<P>
 
<PRE>
   % frmdiff -k &lt;lsk&gt; &lt;sclk&gt; &lt;fk&gt; -t dumpaa -a yes -s &lt;step&gt;
             &lt;ck1&gt; &lt;ck2&gt;
</PRE>
<BR><BR>
<A NAME="To Sample Quaternions from a CK File"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> To Sample Quaternions from a CK File
</H3><P><BR><BR>
   To sample orientation provided in a CK file and print it as SPICE-style
   quaternions, run FRMDIFF as follows:
<P>
 
<PRE>
   % frmdiff -k &lt;lsk&gt; &lt;sclk&gt; &lt;fk&gt; -t dumpqs -s &lt;step&gt; &lt;ck&gt;
</PRE>
   where ``&lt;lsk&gt;'', ``&lt;sclk&gt;'', ``&lt;fk&gt;'', and
   ``&lt;ck&gt;'' are the names of LSK, SCLK, FK, and CK files (all four
   are required); ``-t dumpqs'' sets the output format to the SPICE-style
   quaternion dump; and ``step'' is the time step, in seconds. The
   program's output can be re-directed to a file using the ``&gt;'' pipe.
   To print output time tags as UTC in ISO date format, add
<P>
 
<PRE>
   -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
</PRE>
   before ``-k''. To use the ``other''-style quaternion dump instead of the
   SPICE-style quaternion dump, replace ``dumpqs'' with ``dumpqo''. To
   include angular velocities, add ``-a yes'' before ``-s''; to print
   angular velocities in the structure frame rather than the base frame,
   also add ``-m to'', like this (the command line below is wrapped to fit
   the page width):
<P>
 
<PRE>
   % frmdiff -k &lt;lsk&gt; &lt;sclk&gt; &lt;fk&gt; -t dumpqs -a yes -m to
             -s &lt;step&gt; &lt;ck&gt;
</PRE>
<BR><BR>
<A NAME="To Compute Transformation Between Two Frames"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> To Compute Transformation Between Two Frames
</H3><P><BR><BR>
   To compute transformation from one frame known to SPICE to another frame
   known to SPICE and display this transformation as Euler angles, run
   FRMDIFF as follows (the command line below is wrapped to fit the page
   width):
<P>
 
<PRE>
   % frmdiff -k &lt;kernels&gt; -t dumpea
             -b &lt;begintime&gt; -e &lt;endtime&gt; -s &lt;step&gt;
             -f1 &lt;from_frame&gt; -t1 &lt;to_frame&gt;
</PRE>
   where ``&lt;kernels&gt;'' are the names of kernel files needed to
   compute the transformation (an LSK must be included); ``-t dumpea'' sets
   the output format to the Euler angles dump; ``&lt;begintime&gt;'' and
   ``&lt;endtime&gt;'' set the begin and end time, as UTC, for the period
   of interest; ``step'' is the time step, in seconds; and
   ``&lt;from_frame&gt;'' and ``&lt;to_frame&gt;'' are the names of the
   frames from which and to which the transformation can be computed. For
   lengthy reports the program's output should be re-directed to a file
   using the ``&gt;'' pipe.
<P>
 
<BR><BR>
<A NAME="Usage"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Usage
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   FRMDIFF is a command line program with the following usage:
<P>
 
<PRE>
   % frmdiff [options] &lt;first kernel&gt; &lt;second kernel&gt;
   % frmdiff [options] &lt;kernel&gt;
   % frmdiff [options]
</PRE>
   where either of the kernels can be a CK, a PCK, an FK, or any other
   SPICE kernel. The options are:
<P>
 
<PRE>
   -k  &lt;supporting kernel(s) name(s)&gt;
   -f1 &lt;first ``from'' frame, name or ID&gt;
   -t1 &lt;first ``to'' frame, name or ID&gt;
   -c1 &lt;first frame for coverage look up, name or ID&gt;
   -k1 &lt;additional supporting kernel(s) for first file&gt;
   -f2 &lt;second ``from'' frame, name or ID&gt;
   -t2 &lt;second ``to'' frame, name or ID&gt;
   -c2 &lt;second frame for coverage look up, name or ID&gt;
   -k2 &lt;additional supporting kernel(s) for second file&gt;
   -a  &lt;compare angular velocities, yes|no&gt;
   -m  &lt;frame for angular velocities, from|to&gt;
   -b  &lt;interval start time&gt;
   -e  &lt;interval stop time&gt;
   -n  &lt;number of points: 1 to 1000000 (default: 1000)&gt;
   -s  &lt;time step in seconds&gt;
   -f  &lt;time format, et|sclk|sclkd|ticks|picture_for_TIMOUT&gt;
   -t  &lt;report: basic|stats|dumpaa|dumpm|dumpqs|dumpqo|dumpea
       |dumpc|dumpg&gt;
   -o  &lt;rotation axes order (default: z y x)&gt;
   -x  &lt;units for output angles&gt;
</PRE>
   The order of options and case of the option keys are not significant.
   The values provided after the option keys must be separated from keys by
   one or more spaces. Un-recognized options are not specifically checked
   for; instead they are treated as continuation of the value provided
   using the preceding recognized option.
<P>
 
<BR><BR>
<A NAME="Options"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Options
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Kernel file names and control parameters are provided to the program
   using the following command line options (only a brief description of
   each option is given in the list below; details, defaults, and
   dependencies are discussed later in this document):
<P>
 
<DL><DT>
<B>
 &lt;first kernel&gt;
</B><BR><BR>
<DD>
 is the name of the first primary kernel. When two primary kernels are
provided to the program this name must be the second to last item on
the command line.<BR>
</DL>
<DL><DT>
<B>
 &lt;second kernel&gt;
</B><BR><BR>
<DD>
 is the name of the second primary kernel. When two primary kernels are
provided to the program this name must be the last item on the command
line.<BR>
</DL>
<DL><DT>
<B>
 &lt;kernel&gt;
</B><BR><BR>
<DD>
 is the name of the only primary kernel. When only one primary kernel is
provided to the program this name must be the last item on the command
line.<BR>
</DL>
<DL><DT>
<B>
 -k &lt;kernels&gt;
</B><BR><BR>
<DD>
 is used to specify the list of additional kernels that should be used
for both frame transformations to be computed. Kernel names following
``-k'' must be separated by spaces.<BR>
</DL>
<DL><DT>
<B>
 -f1 &lt;frame&gt;
</B><BR><BR>
<DD>
 is used to specify the ``from'' frame for the first (or only) frame
transformation to be computed. This frame must be known to SPICE and
can be specified using the frame name, ID, or class ID.<BR>
</DL>
<DL><DT>
<B>
 -t1 &lt;frame&gt;
</B><BR><BR>
<DD>
 is used to specify the ``to'' frame for the first (or only) frame
transformation to be computed. This frame must be known to SPICE and
can be specified using the frame name, ID, or class ID.<BR>
</DL>
<DL><DT>
<B>
 -c1 &lt;frame&gt;
</B><BR><BR>
<DD>
 is used to specify the ``coverage'' frame to be used to look up
coverage from the first (or only) primary kernel file. This frame must
be known to SPICE and can be specified using the frame name, ID, or
class ID. The first (or only) primary kernel file must be a CK or a
binary PCK and must contain data for this frame.<BR>
</DL>
<DL><DT>
<B>
 -k1 &lt;kernels&gt;
</B><BR><BR>
<DD>
 is used to specify the list of additional kernels that should be used
only for the first frame transformation to be computed. Kernel names
following ``-k1'' must be separated by spaces.<BR>
</DL>
<DL><DT>
<B>
 -f2 &lt;frame&gt;
</B><BR><BR>
<DD>
 is used to specify the ``from'' frame for the second (or only) frame
transformation to be computed. This frame must be known to SPICE and
can be specified using the frame name, ID, or class ID.<BR>
</DL>
<DL><DT>
<B>
 -t2 &lt;frame&gt;
</B><BR><BR>
<DD>
 is used to specify the ``to'' frame for the second (or only) frame
transformation to be computed. This frame must be known to SPICE and
can be specified using the name, ID, or class ID.<BR>
</DL>
<DL><DT>
<B>
 -c2 &lt;frame&gt;
</B><BR><BR>
<DD>
 is used to specify the ``coverage'' frame to be used to look up
coverage from the second (or only) primary kernel file. This frame must
be known to SPICE and can be specified using the name, ID, or class ID.
The second (or only) primary kernel file must be a CK or a binary PCK
and must contain data for this frame.<BR>
</DL>
<DL><DT>
<B>
 -k2 &lt;kernels&gt;
</B><BR><BR>
<DD>
 is used to specify the list of additional kernels that should be used
only for the second frame transformation to be computed. Kernel names
following ``-k2'' must be separated by spaces.<BR>
</DL>
<DL><DT>
<B>
 -b &lt;time&gt;
</B><BR><BR>
<DD>
 is used to specify the coverage window begin time. This option must be
provided when no primary kernels are specified or neither of the
specified primary kernels is a CK or a binary PCK. The time string
provided using this option can be in any form accepted by SPICE's
<a href="../cspice/str2et_c.html">str2et_c</a> function.<BR>
</DL>
<DL><DT>
<B>
 -e &lt;time&gt;
</B><BR><BR>
<DD>
 is used to specify the coverage window end time. This option must be
provided when no primary kernels are specified or neither of the
specified primary kernels is a CK or a binary PCK. The time string
provided using this option can be in any form accepted by SPICE's
<a href="../cspice/str2et_c.html">str2et_c</a> function.<BR>
</DL>
<DL><DT>
<B>
 -n &lt;number&gt;
</B><BR><BR>
<DD>
 is used to specify the number of points within the coverage window, for
which the frame transformation(s) must be computed. The number must be
an integer between 1 and 1,000,000. The default value is 1000.<BR>
</DL>
<DL><DT>
<B>
 -s &lt;step&gt;
</B><BR><BR>
<DD>
 is used to specify the step, in seconds, for determining points within
the coverage window, for which the frame transformation(s) must be
computed. The step must be greater than 1E-8. This option supersedes
``-n''.<BR>
</DL>
<DL><DT>
<B>
 -t &lt;report_type&gt;
</B><BR><BR>
<DD>
 is used specify the type of report that the program should display:<BR>
</DL>
<PRE>
                             basic   to display only the maximum
                                     rotation angle and angular
                                     velocity (AV) magnitude (default)
 
                             stats   to display statistics on rotation
                                     angles and AVs
 
                             dumpaa  to display a table of rotation
                                     angles and axes
 
                             dumpm   to display a table of matrices
 
                             dumpqs  to display a table of SPICE-style
                                     quaternions
 
                             dumpqo  to display a table of ``other''-
                                     style quaternions
 
                             dumpea  to display a table of Euler angles
 
                             dumpc   to display a table of coverage
                                     intervals
 
                             dumpg   to display a table of coverage
                                     gaps
</PRE>
<DL><DT>
<B>
 -a &lt;av_flag&gt;
</B><BR><BR>
<DD>
 is used to tell the program whether angular velocities should be
computed along with rotations:<BR>
</DL>
<PRE>
                             no      to compute only rotations
                                     (default)
 
                             yes     to compute rotations and
                                     angular velocities
</PRE>
<DL><DT>
<B>
 -m &lt;av_frame&gt;
</B><BR><BR>
<DD>
 is used to tell the program in which frame angular velocities should be
reported:<BR>
</DL>
<PRE>
                             from    to output angular velocities in
                                     ``from'' frame (default)
 
                             to      to output angular velocities in
                                     ``to'' frame
</PRE>
<DL><DT>
<B>
 -f &lt;time_type&gt;
</B><BR><BR>
<DD>
 is used to specify the type of time tag to be used in tabular reports
(``-t'' with ``dumpm'', ``dumpqs'', ``dumpqo'', ``dumpea'', ``dumpc'',
or ``dumpg''):<BR>
</DL>
<PRE>
                             et      to display times as TDB seconds
                                     past J2000 (default)
 
                             sclk    to display times as string SCLKs
 
                             sclkd   to display times as decimal SCLKs
 
                             ticks   to display times as encoded SCLK
                                     ticks
 
                             &lt;PICT&gt;  any time format picture accepted
                                     by the @TIMOUT @routine (for
                                     example ``YYYY-MM-DDTHR:MN:SC.###
                                     ::RND'' for time tags for be
                                     displayed as UTCs in ISO date
                                     format)
</PRE>
<DL><DT>
<B>
 -o &lt;axes&gt;
</B><BR><BR>
<DD>
 is used to specify the list of axes determining the order of rotations
used for converting rotation matrices to Euler angles. The value must
be a space-delimited list of three axes from the set of ``X'', ``Y'',
``Z'' (case-insensitive). The second axis must differ from the first
and third axes. The default order is ``Z Y X''.<BR>
</DL>
<DL><DT>
<B>
 -x &lt;units&gt;
</B><BR><BR>
<DD>
 is used to specify the units for the angles in the rotation angle and
axis dump (``-t dumpaa'') and Euler angle dump (``-t dumpea'') reports;
ignored for all other report types. Supported units are:<BR>
</DL>
<PRE>
                             radians (default)
                             degrees
                             arcminutes
                             arcseconds
                             hourangle
                             minuteangle
                             secondangle
</PRE>
<DL><DT>
<B>
 -v
</B><BR><BR>
<DD>
 causes the program to display only the version line. This option
overrides all other options.<BR>
</DL>
<DL><DT>
<B>
 -u
</B><BR><BR>
<DD>
 causes the program to display the usage message. This option overrides
all other options except ``-v''.<BR>
</DL>
<DL><DT>
<B>
 -h
</B><BR><BR>
<DD>
 causes the program to display a brief help message. This option
overrides all other options except ``-v'' and ``-u''.<BR>
</DL>
<BR><BR>
<A NAME="Inputs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Inputs
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   For a successful run the program must be supplied with kernel files
   providing sufficient data to compute the frame transformation(s) of
   interest, and with control parameters clearly specifying, together with
   default values determined from the kernels, what transformations should
   be computed and at what times. Both the kernels and the control
   parameters are provided to the program using command line options.
<P>
 
<BR><BR>
<A NAME="Kernel Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Kernel Files
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In most cases one or more kernel files must be provided to the program
   to perform comparison or sampling of frame orientations. Depending on
   how the kernel files are provided, they fall into one of two categories
   -- primary kernel files and additional kernel files.
<P>
 
   Primary kernel files -- two, one, or none -- are provided at the end of
   the command line without any command line keys. Normally these kernel
   files are the ones containing orientations that differ (for example,
   predicted and reconstructed CKs for the same frame and time period, two
   versions of an FK with different alignment data for the same frame,
   etc.), or the orientation to be sampled. These kernel files are also
   examined by the program to determine the default values for the
   ``from'', ``to'', and ``cov'' frames, and to determine the coverage
   window boundaries.
<P>
 
   Additional kernel files -- none, or as many as needed -- are provided
   anywhere on the command line (except at the very end) using the ``-k'',
   ``-k1'', and ``-k2'' keys. Normally these kernel files contain
   additional SPICE data needed to compute requested orientations (for
   example, LSK and SCLK files providing supporting time conversion data,
   FK files providing frame definitions needed by SPICE to recognize
   specified frames, etc).
<P>
 
<BR><BR>
<A NAME="Primary Kernel Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Primary Kernel Files
</H3><P><BR><BR>
   The primary kernels can be of any type -- CK, PCK, FK, SCLK, LSK or even
   SPK -- and are provided as the last or the last two items on the command
   line. Since the primary kernel files do not require specific command
   line keys, the program determines if they were given by examining the
   last two words on the command line as follows:
<P>
 
<UL>
<TT>--</TT> If the last word on the command line is not the name of an existing file,
the program assumes that no primary kernel files were given.
<BR><BR></UL>
<UL>
<TT>--</TT> If the last word on the command line is the name of an existing file but
the second to last word is not, the program assumes that only one primary
kernel was given.
<BR><BR></UL>
<UL>
<TT>--</TT> If both last two words are names of existing files, the program assumes
that it was given two primary kernel files
<BR><BR></UL>
   Due to the parsing approach described above, misspelling a primary
   kernel name leads to the program deciding that it either runs with no
   primary kernel files (if the last file name is misspelled) or that it
   runs with one primary kernel instead of two (if the second to last file
   name is misspelled). In either case, the misspelled file name(s) is(are)
   treated as a part of the value of the command line option immediately
   preceding it(them) causing the program to signal an error indicating an
   incorrect option value.
<P>
 
   On the other hand, if any of the options for specifying additional
   kernel files (``-k'', ``-k1'', ``-k2'') followed by actual files names
   is provided at the end of the command line (for the case of no primary
   kernels) or immediately preceding the only primary file (for one primary
   kernel case), the last one or the last two additional kernels are
   mistakenly picked as the primary kernel(s). In this situation the
   program usually signals an error indicating that orientation could not
   be computed because insufficient data was loaded.
<P>
 
<BR><BR>
<A NAME="Additional Kernel Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Additional Kernel Files
</H3><P><BR><BR>
   As for primary kernels, additional kernels can also be of any type --
   CK, PCK, FK, SCLK, LSK or even SPK. Unlike primary kernels, additional
   kernels are specified using the dedicated ``-k'', ``-k1'', and ``-k2''
   keys. Any number of additional kernels can be provided using any of the
   three keys, with kernel file names listed in any order, separated by
   blanks. While in some rare cases no additional kernel files are
   required, in most cases at least an LSK file and an SCLK file containing
   time correlation data and an FK file containing frame definitions should
   be specified using these keys. The additional kernels are used by the
   program as follows:
<P>
 
<UL>
<TT>--</TT> All additional kernel files provided using the ``-k'' are loaded and used
for both ``from''-``to'' frame combinations.
<BR><BR></UL>
<UL>
<TT>--</TT> All additional kernel files provided using ``-k1'' are loaded and used only
for the first ``from''-``to'' frame combination.
<BR><BR></UL>
<UL>
<TT>--</TT> All additional kernel files provided using ``-k2'' are loaded and used only
for the second ``from''-``to'' frame combination.
<BR><BR></UL>
   Neither the combined set of additional kernel files given using
   ``-k''/``-k1'' nor the combined set of additional kernel files given
   using ``-k''/``-k2'' can contain enough data to compute corresponding
   orientations at any time in the time buffer without loading the
   corresponding primary file(s). If they do, the program signals an error.
   The two exceptions from this requirement are:
<P>
 
<UL>
<TT>--</TT> when no primary kernel files are specified the additional kernel files
given using ``-k''/``-k1'' and ``-k''/``-k2'' should contain enough data to
compute the corresponding orientations
<BR><BR></UL>
<UL>
<TT>--</TT> when both ``from'' and ``to'' frames in one or both``from''-``to'' frame
pairs are built-in frames, the check for inability to compute orientations
without loading primary kernel files is skipped
<BR><BR></UL>
<BR><BR>
<A NAME="Comparison Runs vs. Sampling Runs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Comparison Runs vs. Sampling Runs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The program automatically decides whether it should compare two
   orientations or sample one orientation, based on the primary kernels
   provided at the end of the command line, additional kernel files
   provided using the ``-k1'' and ``-k2'' keys, and on the ``from'' and
   ``to'' frames specified on the command line using the ``-f1'', ``-t1'',
   ``-f2'', and ``-t2'' keys and/or determined from the primary kernel
   data.
<P>
 
   To run the program in comparison mode, it is enough to satisfy any of
   the following guidelines for specifying inputs that tell the program to
   compute two different orientations:
<P>
 
<UL>
<TT>--</TT> provide two different primary kernels
<BR><BR></UL>
<UL>
<TT>--</TT> provide two different sets of orientation-specific additional kernels using
``-k1'' and ``-k2''
<BR><BR></UL>
<UL>
<TT>--</TT> specify two different ``from'' frames using ``-f1'' and ``-f2''
<BR><BR></UL>
<UL>
<TT>--</TT> specify two different ``to'' frames using ``-t1'' and ``-t2''
<BR><BR></UL>
   To run the program in sampling mode, it is required to satisfy all of
   the following guidelines telling the program to compute a single
   orientation:
<P>
 
<UL>
<TT>--</TT> provide only one primary kernel or no primary kernels
<BR><BR></UL>
<UL>
<TT>--</TT> provide no orientation-specific additional kernels using ``-k1'' and
``-k2''
<BR><BR></UL>
<UL>
<TT>--</TT> specify only one ``from'' frame using either ``-f1'' or ``-f2'' or no
``from'' frames
<BR><BR></UL>
<UL>
<TT>--</TT> specify only one ``to'' frame using either ``-t1'' or ``-t2'' or no ``to''
frames
<BR><BR></UL>
   There are only two cases when the program runs in sampling mode after
   being given two primary kernels and/or two orientation-specific
   additional kernel sets. These cases are:
<P>
 
<UL>
<TT>--</TT> When run with two primary kernel files, the program samples orientation
only if these kernel files are the same file and additional kernel files
provided using the ``-k1''/``-k2'' keys are the same files listed the same
order and ``from'' frames provided using the ``-f1''/``-f2'' keys or
determined automatically are the same and ``to'' frames provided using the
``-t1''/``-t2'' keys or determined automatically are the same.
<BR><BR></UL>
<UL>
<TT>--</TT> When ran with one primary kernel or no primary kernel files but with some
orientation-specific additional kernels, program will sample orientation
only if additional kernel files provided using the ``-k1''/``-k2'' keys are
the same files listed the same order and ``from'' frames provided using the
``-f1''/``-f2'' keys or determined automatically are the same and ``to''
frames provided using the ``-t1''/``-t2'' keys or determined automatically
are the same.
<BR><BR></UL>
<BR><BR>
<A NAME="Runs with Two, One, and No Primary Kernel File(s)"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Runs with Two, One, and No Primary Kernel File(s)
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The number and types of primary kernel files and the mode in which the
   program is run (``comparing'' vs. ``sampling'') directly affect the
   requirements in regards to which command line options must be provided,
   approaches for determining default values for omitted options, and ways
   in which kernels are loaded and orientations are computed. The three
   subsections below discuss specifics of runs with two, one, and no
   primary kernel files.
<P>
 
<BR><BR>
<A NAME="Runs with Two Primary Kernel Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Runs with Two Primary Kernel Files
</H3><P><BR><BR>
   When two primary kernel files are provided on the command line:
<P>
 
<UL>
<TT>--</TT> All ``-*1'' and ``-*2'' options, and ``-b'' and ``-e'' options can be
omitted if one of the primary files (or both primary files) are a CK or a
binary PCK, for which defaults for these options can be picked from the
file(s).
<BR><BR></UL>
<UL>
<TT>--</TT> ``-f1'' or ``-f2'' or both, ``-t1'' or ``-t2'' or both, and ``-b'' and
``-e'' must be specified if neither of the primary files is a CK or binary
PCK because the program has no way of picking defaults for the ``from''
frame(s), ``to'' frame(s), and time boundaries for any other types of
kernels.
<BR><BR></UL>
<UL>
<TT>--</TT> If the program is run in comparison mode, the first primary file and the
additional kernel files given using ``-k'' and ``-k1'' are loaded and
orientations for the first default/specified ``from''-``to'' frame
combination are computed at times within the default/specified time window,
then the second primary file and the additional kernel files given using
``-k'' and ``-k2'' are loaded and orientations for the second
default/specified ``from''-``to'' frame combination are computed at the
same times within the default/specified time window, then the differences
between the corresponding orientations are computed and printed in the
specified format.
<BR><BR></UL>
<UL>
<TT>--</TT> If the program is run in sampling mode, the first primary file and the
additional kernel files given using ``-k'' and ``-k1'' are loaded and
orientations for the first default/specified ``from''-``to'' frame
combination are computed at times within the default/specified time window
and printed in the specified format.
<BR><BR></UL>
<BR><BR>
<A NAME="Runs with One Primary Kernel File"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Runs with One Primary Kernel File
</H3><P><BR><BR>
   When one primary kernel file is provided on the command line:
<P>
 
<UL>
<TT>--</TT> All ``-*1'' and ``-*2'' options, and ``-b'' and ``-e'' options can be
omitted if the primary file is a CK or a binary PCK, for which defaults for
these options can be picked from the file.
<BR><BR></UL>
<UL>
<TT>--</TT> ``-f1'' or ``-f2'' or both, ``-t1'' or ``-t2'' or both, and ``-b'' and
``-e'' must be specified if the primary file is not a CK or a binary PCK
because the program has no way of picking defaults for the ``from''
frame(s), ``to'' frame(s) and time boundaries for any other types of
kernels.
<BR><BR></UL>
<UL>
<TT>--</TT> If the program is run in comparison mode, the primary file and the
additional kernel files given using ``-k'' and ``-k1'' are loaded and
orientations for the first ``from''-``to'' frame combination are computed
at times within the default/specified time window, then the primary file
and the additional kernel files given using ``-k'' and ``-k2'' are loaded
and orientations for the second ``from''-``to'' frame combination are
computed at the same times within the default/specified time window, then
the differences between corresponding orientations are computed and printed
in the specified format.
<BR><BR></UL>
<UL>
<TT>--</TT> If the program is run in sampling mode, the primary file and the additional
kernel files given using ``-k'' and ``-k1'' are loaded and orientations for
the first ``from''-``to'' frame combination are computed at times within
the default/specified time window and then printed in the specified format.
<BR><BR></UL>
<BR><BR>
<A NAME="Runs Without Primary Kernel Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Runs Without Primary Kernel Files
</H3><P><BR><BR>
   When no primary kernel files are specified on the command line:
<P>
 
<UL>
<TT>--</TT> ``-f1'' or ``-f2'' or both, ``-t1'' or ``-t2'' or both, and ``-b'' and
``-e'' must be specified because the program has no way of picking defaults
for the ``from'' frame(s), ``to'' frame(s), and time boundaries when it is
not given any primary kernel(s) to examine.
<BR><BR></UL>
<UL>
<TT>--</TT> If the program is run in comparison mode, the additional kernel files given
using ``-k'' and ``-k1'' are loaded and orientations for the first
``from''-``to'' frame combination are computed at times within the
default/specified time window, then the additional kernel files given using
``-k'' and ``-k2'' are loaded and orientations for the second
``from''-``to'' frame combination are computed at the same times within the
default/specified time window, then the differences between corresponding
orientations are computed and printed in the specified format.
<BR><BR></UL>
<UL>
<TT>--</TT> If the program is run in sampling mode, the additional kernel files given
using ``-k'' and ``-k1'' are loaded and orientations for the first
``from''-``to'' frame combination are computed at times within the
default/specified time window and then printed in the specified format.
<BR><BR></UL>
<BR><BR>
<A NAME="``From'', ``To'', and ``Coverage'' Frames"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> ``From'', ``To'', and ``Coverage'' Frames
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The program has six command line keys -- ``-f1'', ``-t1'', ``-c1'',
   ``-f2'', ``-t2'', and ``-c2'' -- to specify frames to be used to compute
   rotations (``-f*'' and ``-t*'' keys) and to determine coverage from
   primary CK and binary PCK kernel files (``-c*'' keys). A single frame
   can be specified using each of these keys using the frame name, frame
   ID, or frame class ID (only for runs with primary kernel files that are
   CKs or binary PCKs).
<P>
 
   Whether the frame is specified by the name, ID, or class ID, it must be
   known to SPICE, i.e. it must either be a built-in frame or one of the
   frames defined in the FK file(s) provided as primary or additional
   kernels. If the frame name, ID, or class ID specified on the command
   line or picked from the primary file is not recognized after loading the
   kernel files provided using ``-k''/``-k1'' and the first primary file
   for the ``-*1'' frames, or provided using ``-k''/``-k2'' and the second
   primary file for the ``-*2'' frames, the program signals an error.
<P>
 
   Not all six frames have to be specified for every program run. In fact
   in many cases only one, two, or even no frames can be given and the
   program will set the rest to default values based on the other frames
   that are provided and/or by examining the primary kernel files. The
   three subsections below discuss specifying and picking defaults for the
   ``from'', ``to'', and ``coverage'' frames.
<P>
 
<BR><BR>
<A NAME="``From'' Frames"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> ``From'' Frames
</H3><P><BR><BR>
   The following rules apply to specifying and picking defaults for the
   ``from'' frames:
<P>
 
<UL>
<TT>--</TT> If both ``-f1'' and ``-f2'' are specified, orientations are computed with
respect to these ``from'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If only ``-f1'' or only ``-f2'' is specified, the specified ``from'' frame
is used for both ``from'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-f1'' nor ``-f2'' is specified and only one of the primary
kernel files is a CK or a binary PCK, the ``from'' frame from the last
segment of this CK or PCK file is used for both ``from'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-f1'' nor ``-f2'' is specified and both primary kernel files
are CKs or binary PCKs, the ``from'' frame from the last segment of the
first primary CK or PCK file is used for both ``from'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-f1'' nor ``-f2'' is specified and no primary files are given
or neither of the primary files is a CK or binary PCK, the program signals
an error.
<BR><BR></UL>
<BR><BR>
<A NAME="``To'' Frames"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> ``To'' Frames
</H3><P><BR><BR>
   The following rules apply to specifying and picking defaults for the
   ``to'' frames:
<P>
 
<UL>
<TT>--</TT> If ``-t1'' and ``-t2'' are specified, orientations are computed for these
``to'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If only ``-t1'' or only ``-t2'' is specified, the specified ``to'' frame is
used for both ``to'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-t1'' nor ``-t2'' is specified and only one of the primary
kernel files is a CK or a binary PCK, the frame from the last segment of
this CK or PCK is used for both ``to'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-t1'' nor ``-t2'' is specified and both primary kernel files
are CKs or binary PCKs, the frame from the last segment of the first CK or
PCK is used for both ``to'' frames.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-t1'' nor ``-t2'' is specified and no primary files are given
or neither of the primary files is a CK or binary PCK, the program signals
an error.
<BR><BR></UL>
<BR><BR>
<A NAME="``Coverage'' Frames"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> ``Coverage'' Frames
</H3><P><BR><BR>
   The following rules apply to specifying and picking defaults for the
   ``coverage'' frames:
<P>
 
<UL>
<TT>--</TT> If ``-c1'' and ``-c2'' are specified, these frames are used to look up
coverage in the corresponding primary CK or PCK files or file (if only one
primary file is specified).
<BR><BR></UL>
<UL>
<TT>--</TT> If only ``-c1'' or only ``-c2'' is specified, the specified frame is used
to look up coverage from the corresponding primary file.
<BR><BR></UL>
<UL>
<TT>--</TT> If neither ``-c1'' nor ``-c2'' is specified and the corresponding primary
file is a CK or binary PCK, the specified/default ``from'' frame
(``-f1''/``-f2'') is used to look up coverage from the file.
<BR><BR></UL>
<UL>
<TT>--</TT> If a coverage look up frame is specified for primary kernel file that is
not a CK or a binary PCK, the program signals an error.
<BR><BR></UL>
<UL>
<TT>--</TT> If there is no coverage for the specified frame in the corresponding CK or
PCK primary file, the program signals an error.
<BR><BR></UL>
<BR><BR>
<A NAME="Times for Comparison/Sampling"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Times for Comparison/Sampling
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The program picks times at which orientation(s) are computed based on
   the coverage window determined by examining the primary files(s) and/or
   specified using the ``-b'' and ``-e'' keys, and on either the number of
   points within that window specified using the ``-n'' key or the time
   step specified using the ``-s'' key''.
<P>
 
   The coverage window begin and end times specified using the ``-b'' and
   ``-e'' options can be in any format accepted by SPICE's <a href="../cspice/str2et_c.html">str2et_c</a>
   function (see <a href="../cspice/str2et_c.html">str2et_c</a> header for details). If one or both of these
   times are provided, an LSK file must be provided as one of the
   additional or primary kernels.
<P>
 
   The number of points specified using the ``-n'' key must be an integer
   between 1 to 1,000,000 while the step specified using the ``-s'' key
   must be in seconds and be greater than 1.0E-8. If both ``-n'' and ``-s''
   are specified, ``-s'' takes precedence.
<P>
 
   The coverage window determined by examining the primary kernels --
   especially if one or both of these primary kernels is a CK file, which
   frequently have gaps in coverage -- may consist of many intervals, some
   of which may be singletons (with the interval begin time equal to the
   interval end time). Whether the coverage window consists of only one
   interval or of many intervals, the program computes times within the
   window in such a way that the interval ends are always included in the
   set of points. The rest of times are distributed within the intervals,
   stepping from the beginning of each interval with the specified step. If
   the number of points is given instead of the step, the step is computed
   using the measure of the coverage window (the sum of the lengths of the
   individual intervals) and the specified number of points.
<P>
 
   Not all of the keys controlling selection of points have to be specified
   for every program run. In some cases none of these options are required;
   in the other cases ``-b'' and ``-e'' must be specified. The two
   subsections below discuss specifics of providing and picking defaults
   for the coverage window and step or number of points.
<P>
 
<BR><BR>
<A NAME="Coverage Window"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Coverage Window
</H3><P><BR><BR>
   The program determines the coverage window either by examining the
   primary kernels (resulting in the ``default coverage window''), or by
   using the begin and end times specified using the ``-b'' and ``-e''
   keys, or as a combination of both.
<P>
 
   The default coverage window can be determined only from the primary
   kernel files that are binary PCK files (using SPICE's <a href="../cspice/pckcov_c.html">pckcov_c</a> function)
   or CK files (using SPICE's <a href="../cspice/ckcov_c.html">ckcov_c</a> function) and only if these kernels
   contain data for the ``coverage'' frames either specified using the
   ``-c1''/``-c2'' keys or set to default values as described earlier in
   this document. When the two primary files are two CK files or two binary
   PCK files or a binary PCK file and a CK file, the default coverage
   window is set to the intersection of the coverage windows determined for
   each of the two files.
<P>
 
   If the default coverage window was determined from the primary kernel
   file(s) and either ``-b'' or ``-e'', or both ``-b'' and ``-e'' were
   specified, the window is truncated according to these begin and end
   times. If the time specified using ``-b'' is before the start of the
   default window, this time is ignored. If the time specified using ``-b''
   is after the end of the default coverage window, the program signals an
   error. If the time specified using ``-e'' is after the end of the
   default window, this time is ignored. If the time specified using ``-e''
   is before the start of the default coverage window, the program signals
   an error.
<P>
 
   If the program was given no primary kernel files, or if the primary
   kernel files are not CKs or binary PCKs, both the coverage window begin
   time and the coverage window end time must be specified using the ``-b''
   and ``-e'' keys because the program has no way to determining the
   default coverage window. If either ``-b'' or ``-e'' is not provided in
   such cases, the program signals an error.
<P>
 
<BR><BR>
<A NAME="Times within Coverage Window"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Times within Coverage Window
</H3><P><BR><BR>
   The program picks times within the coverage window based on the number
   of points specified using the ``-n'' key or the time step specified
   using the ``-s'' key''.
<P>
 
   When neither the number of points is specified using ``-n'' nor the step
   is specified using ``-s'', the number of points is set to a default
   value determined by examining the coverage window. If the total number
   of endpoints -- 2 for each non-singleton interval, 1 for each singleton
   interval -- for all intervals in the coverage window is greater than
   1000, the number of points is set to the number of endpoints and the
   step is not computed. Otherwise it is set to 1000 or a number less than
   but close to 1000 (the actual number is determined at run-time based on
   the lengths of the intervals) and the step is computed by dividing the
   measure of the coverage window by the number of points minus the number
   of endpoints.
<P>
 
   When the number of points is specified using ``-n'' but this number is
   less than the number of the coverage window interval endpoints, the
   value given using ``-n'' is ignored and the number of points is set to
   the number of interval endpoints and the step is not computed. Otherwise
   the number of points is set to the value provided using ``-n'' or a
   number less than but close to this value (the actual number is
   determined at run time based on the lengths of the intervals) and the
   step is computed by dividing the measure of the coverage window by the
   number of points minus the number of endpoints.
<P>
 
   When step is specified using ``-s'', the number of points is computed by
   adding the number of interval endpoints to the total of the numbers of
   points that can fit within each non-singleton interval when it's stepped
   through with this step. If the resultant number of points is greater
   than 1,000,000, the program signals an error.
<P>
 
   Whether the step was provided or computed using the provided or default
   number of points, the set of times at which orientation is computed
   includes all interval ends -- 2 for each non-singleton interval, 1 for
   each singleton interval -- plus additional points computed by stepping
   with this step within each non-singleton interval starting from the
   interval start time. The last point within each non-singleton interval
   is computed such that it always lies inside the 1.5*step to 0.5*step
   range off the interval end.
<P>
 
   Care should be taken when picking the step using ``-s'' or specifying
   the number of points using ``-n''. Picking a very small step for a large
   time window, or very many points for any window, leads to very long run
   times. In some cases the number of points computed using the step may
   even be greater that 1,000,000, preventing the program from running
   because its buffers are not large enough to deal with so many points. On
   the other hand, picking a large step or too few points prevents the
   program from doing a thorough comparison.
<P>
 
<BR><BR>
<A NAME="Angular Velocities"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Angular Velocities
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The ``-a'' key is used to tell the program to compute angular velocities
   in addition to orientations. When the value provided using ``-a'' is
   ``yes'', the program computes angular velocities and reports them or
   their differences along with the orientation or orientation differences.
   If the key is omitted or set to ``no'', the program does not compute
   angular velocities. For any value other than ``yes'' or ``no'' the
   program reports an error.
<P>
 
   If the program samples or compares angular velocities (``-a yes''), the
   ``-m'' key is used to specify whether they or their differences should
   be reported in the ``from'' frame(s) or the ``to'' frame(s). When the
   value provided using the ``-m'' key is ``to'', the program reports
   angular velocities or their differences in the ``to'' frames. If the key
   is omitted or set to ``from'', the program reports angular velocities or
   their differences in the ``from'' frames. For any value other than
   ``to'' or ``from'' the program reports an error.
<P>
 
   In order for the program to compute angular velocities the data provided
   to it must support this computation. This is not an issue for any frames
   except for CK-based frames. Therefore, when using CK files, whether as
   primary or as additional kernels, it's important to make sure that these
   CKs include angular velocities before requesting the program to compute
   angular velocities.
<P>
 
<BR><BR>
<A NAME="Output"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Output
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   In a successful run the program prints to the screen a report consisting
   of the report header and report data. The report header provides the
   complete information about kernels and control parameters used by the
   program. The report data provides information about the orientation and
   angular velocity differences (for comparison runs) or orientations and
   angular velocities (for sampling reports) in a variety of ways, called
   report types. The algorithms used to compute orientations and angular
   velocities and their differences and to convert them to various
   representations used in the reports are shown in ``Appendix 1''.
<P>
 
<BR><BR>
<A NAME="Overview of Report Types"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Overview of Report Types
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The report data can be of one of the following types depending on the
   value provided using the ``-t'' key:
<P>
 
<DL><DT>
<B>
 basic
</B><BR><BR>
<DD>
 the basic report including only the maximum and the average rotation
angle difference (for comparison runs) or rotation angle (for sampling
runs) and, if requested, the maximum and the average angular velocity
magnitude difference (for comparison runs) or angular velocity
magnitude (for sampling runs). This is the default report displayed
when ``-t'' is omitted.<BR>
</DL>
<DL><DT>
<B>
 stats
</B><BR><BR>
<DD>
 the statistics report including a small set of statistical information
on the difference between two frame orientations (for comparison runs)
or statistics on a single orientation (for sampling runs). In addition
to the items from the basic report (maximums and averages), this report
includes RMS of the rotation angle difference/angle and angular
velocity difference/angular velocity and the times when the maximum
value of the rotation angle difference/angle and the angular velocity
difference/angular velocity were found.<BR>
</DL>
<DL><DT>
<B>
 dumpaa
</B><BR><BR>
<DD>
 the angle and axis dump report containing a table listing the
orientation difference (for comparison runs) or orientation (for
sampling runs) expressed as the rotation angle and axis and, if
requested, the components and the magnitude of the angular velocity
difference (for comparison runs) or angular velocity (for sampling
runs), along with the time, for each of the times at which the
orientations were computed.<BR>
</DL>
<DL><DT>
<B>
 dumpm
</B><BR><BR>
<DD>
 the matrix dump report containing a table listing the orientation
difference (for comparison runs) or orientation (for sampling runs)
expressed as a 3x3 rotation matrix and, if requested, the components of
the angular velocity difference (for comparison runs) or angular
velocity (for sampling runs), along with the time, for each of the
times at which the orientations were computed.<BR>
</DL>
<DL><DT>
<B>
 dumpqs
</B><BR><BR>
<DD>
 the SPICE-style quaternion dump report containing a table listing the
orientation difference (for comparison runs) or orientation (for
sampling runs) expressed as a SPICE-style quaternion and, if requested,
the components of the angular velocity difference (for comparison runs)
or angular velocity (for sampling runs), along with the time, for each
of the times at which the orientations were computed.<BR>
</DL>
<DL><DT>
<B>
 dumpqo
</B><BR><BR>
<DD>
 produces the ``other''-style quaternion dump report containing a table
listing the orientation difference (for comparison runs) or orientation
(for sampling runs) expressed as SPICE-style quaternion and, if
requested, the components of the angular velocity difference (for
comparison runs) or angular velocity (for sampling runs), along with
the time, for each of the times at which the orientations were
computed.<BR>
</DL>
<DL><DT>
<B>
 dumpea
</B><BR><BR>
<DD>
 the Euler angle dump report containing a table listing the orientation
difference (for comparison runs) or orientation (for sampling runs)
expressed as three Euler angles and, if requested, the components of
the angular velocity difference (for comparison runs) or angular
velocity (for sampling runs), along with the time, for each of the
times at which the orientations were computed.<BR>
</DL>
<DL><DT>
<B>
 dumpc
</B><BR><BR>
<DD>
 the coverage intervals dump report containing a table listing the start
and stop times and durations for the intervals inside the coverage
window, during which orientation(s) can be computed.<BR>
</DL>
<DL><DT>
<B>
 dumpg
</B><BR><BR>
<DD>
 the coverage gaps dump report containing a table listing the start and
stop times and duration for the gaps inside the coverage window, during
which orientation(s) cannot be computed.<BR>
</DL>
   The ``basic'' and ``stats'' report are useful for quick assessment of
   whether and by how much two frame transformations differ (for comparison
   runs) or of the maximum/average magnitude of one frame transformation
   (for sampling runs). The ``dumpaa'', ``dumpm'', ``dumpqs'', ``dumpqo'',
   and ``dumpea'' are useful to capture detailed information about
   differences of two transformations (in comparison runs) or information
   about a single transformation (for sampling runs) in various formats as
   a function of time, for analysis or use in other applications. The
   ``dumpc'' and ``dumpg'' reports are useful for CK or binary PCK coverage
   overlap analysis.
<P>
 
   All reports have rigid formats. The only items in the reports that can
   be altered by command line options are:
<P>
 
<UL>
<TT>--</TT> the format of time tags in all ``dump*'' reports; the time format is
changed using the ``-f'' key
<BR><BR></UL>
<UL>
<TT>--</TT> units for the angles in the dump reports that include angles (``dumpaa''
and ``dumpea''); the units are changed using the ``-x'' key
<BR><BR></UL>
<UL>
<TT>--</TT> the order of rotations in the Euler angles dump report (``dumpea''); the
order is changed using the ``-o'' key
<BR><BR></UL>
<UL>
<TT>--</TT> absence or presence of angular velocities in all non-coverage related dump
reports (``dumpaa'', ``dumpm'', ``dumpqs'', ``dumpqo'', and ``dumpea'');
whether angular velocities are included or not is controlled by the ``-a''
key as discussed earlier in this document.
<BR><BR></UL>
<BR><BR>
<A NAME="Time Tag Format for ``dump*'' Reports"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Time Tag Format for ``dump*'' Reports
</H3><P><BR><BR>
   The format of the time tags in the ``dump*'' reports is controlled using
   the ``-f'' key. The following values can be provided using ``-f'':
<P>
 
<DL><DT>
<B>
 et
</B><BR><BR>
<DD>
 to display times as TDB seconds past J2000 (default format when ``-f''
is omitted)<BR>
</DL>
<DL><DT>
<B>
 sclk
</B><BR><BR>
<DD>
 to display times as string SCLKs<BR>
</DL>
<DL><DT>
<B>
 sclkd
</B><BR><BR>
<DD>
 to display times as decimal SCLKs<BR>
</DL>
<DL><DT>
<B>
 ticks
</B><BR><BR>
<DD>
 to display times as encoded SCLK ticks<BR>
</DL>
<DL><DT>
<B>
 &lt;PICTUR&gt;
</B><BR><BR>
<DD>
 a time format picture acceptable for <a href="../cspice/timout_c.html">timout_c</a> function. For example:<BR>
</DL>
<PRE>
                    YYYY-MM-DDTHR:MN:SC.### ::RND    for UTC ISO date
                    YYYY-DOYTHR:MN:SC.### ::RND      for UTC ISO DOY
                    JULIAND.######### ::TDB          for Julian day TDB
</PRE>
   When one of the SCLK formats (``sclk'', ``sclkd'', ``ticks'') is
   specified, TDB times used internally by the program are converted to
   SCLK times using the SCLK ID associated with one of the ``to'' or
   ``coverage'' CK-based frames in the following priority order (from
   highest to lowest): first ``to'' frame, first ``coverage'' frame, second
   ``to'' frame, second ``coverage'' frame. If neither of the ``to'' or
   ``coverage'' frames is a CK frame, the program signals an error.
<P>
 
   When decimal SCLK tags are requested, the SCLK string returned by
   SPICE's <a href="../cspice/sce2s_c.html">sce2s_c</a> function is converted to ``decimal'' SCLK by stripping
   off the partition, using the left field as the integer part and
   converting the rest of the fields to the decimal fraction of the left
   field using the SCLK field values from the string SCLK and SCLK moduli
   and offsets from the SCLK kernel file. For example, the SCLK string
   ``1/883612839.255'' that has seconds in the left field and a count of
   ticks having duration of 1/256 of a second in the right field is
   converted to this DP SCLK 883612839.996094. This conversion is supported
   only for type 1 clocks.
<P>
 
   ``-f'' does not apply to times in the report header and the statistics
   report, in which the times are always displayed as TDBs in calendar and
   seconds past J2000 formats.
<P>
 
<BR><BR>
<A NAME="Angle Units for ``dumpaa'' and ``dumpea'' Reports"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Angle Units for ``dumpaa'' and ``dumpea'' Reports
</H3><P><BR><BR>
   The angles in the ``dumpaa'' and ``dumpea'' reports can be displayed
   using one of the following units depending on the value provided using
   the ``-x'' key:
<P>
 
<PRE>
                    radians (default)
                    degrees
                    arcminutes
                    arcseconds
                    hourangle
                    minuteangle
                    secondangle
</PRE>
   ``-f'' applies neither to the angles in the basic and statistics reports
   (in which the angles are always displayed in radians) nor to angular
   velocities in any reports (which are always displayed in radians per
   second).
<P>
 
<BR><BR>
<A NAME="Report Header"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Report Header
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The top portion of each report generated by the program is occupied by
   the report header providing complete information about the kernels and
   control parameters used by the program. The format and the set of
   information provided in the report header depends on
<P>
 
<UL>
<TT>--</TT> the type of run (comparison vs. sampling)
<BR><BR></UL>
<UL>
<TT>--</TT> the type of report (data dump, coverage dump, etc.)
<BR><BR></UL>
<UL>
<TT>--</TT> the set of kernels that were provided
<BR><BR></UL>
<UL>
<TT>--</TT> whether angular velocities were computed
<BR><BR></UL>
<UL>
<TT>--</TT> and various miscellaneous control parameters.
<BR><BR></UL>
   All lines in the report header have
<P>
 
<PRE>
   #
</PRE>
   as the first character. This allows common plotting programs, such as
   GNUPLOT, to skip these header lines when plotting the ``dump''-type
   reports generated by the program.
<P>
 
<BR><BR>
<A NAME="Report Header for Comparing Two Orientations"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Report Header for Comparing Two Orientations
</H3><P><BR><BR>
   For runs comparing two orientations the report header has the following
   format (the line numbers given on the left are not present in the actual
   report; they are provided for referencing purposes only):
<P>
 
<PRE>
    1  #
    2  # Comparison of N rotations
    3  #
    4  #    from 'FROM1NAME' (FROM1ID) to 'TO1NAME' (TO1ID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # with N rotations
   12  #
   13  #    from 'FROM2NAME' (FROM2ID) to 'TO2NAME' (TO2ID)
   14  #    computed using
   15  #
   16  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
   17  #       -K2/KERNEL1 -K2/KERNEL2 ... -K2/KERNELm
   18  #       SECONDKERNEL
   19  #
   20  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   21  # within the continuous time period
   22  #
   23  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   24  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   25  #
   26  # including differences in AVs relative to the FRAME frames.
   27  #
   28  # TIMESPEC.
   29  #
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> on lines 2 and 11 ``N'' is replaced with the actual number of comparison
points
<BR><BR></UL>
<UL>
<TT>--</TT> on lines 4 and 13 ``FROM1NAME'', ``FROM1ID'', ``TO1NAME'', ``TO1ID'',
``FROM2NAME'', ``FROM2ID'', ``TO2NAME'', and ``TO2ID'' are replaced with
the actual names/IDs used to compute transformations for comparison
<BR><BR></UL>
<UL>
<TT>--</TT> lines 7, 8, 9, 16, 17, and 18 contain lists of additional kernels provided
using the ``-k'', ``-k1'', and ``-k2'' keys and primary kernels provided at
the end of the command line, listed in the order in which they were loaded
by the program. These lines are present only when corresponding kernel
files are given on the command line.
<BR><BR></UL>
<UL>
<TT>--</TT> on line 20 the actual step replaces ``S'' and ``DDDAYS:HR:MN:SC.MSECND''
(step expressed as days, hours, minutes, seconds). If transformations are
computed only at the interval endpoints, the whole line is replaced with
the following string: ``at continuous coverage intervals' endpoints''
<BR><BR></UL>
<UL>
<TT>--</TT> line 21 has the form shown above when there are no gaps in coverage window.
Otherwise the whole line is replaced with the following string: ``within
the non-continuous (with M gaps) time period'' where ``M'' is replaced with
the actual number of gaps.
<BR><BR></UL>
<UL>
<TT>--</TT> on lines 23 and 24 times are replaced with the first and last times from
the set of times for which the comparison was made.
<BR><BR></UL>
<UL>
<TT>--</TT> lines 26 and 27 are displayed only when angular velocities are compared.
The FRAME is set to ``from'' or ``to'' depending on the frame in which the
angular velocity difference is reported.
<BR><BR></UL>
<UL>
<TT>--</TT> line 28 and 29 are displayed for all report types except ``basic'' and
``stats''. Depending on the output time type specified using the ``-f'' key
TIMESPEC is replaced with one of the following strings:
<BR><BR></UL>
<PRE>
            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID &lt;nnn&gt;.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '&lt;format&gt;' format.''
</PRE>
<UL>
<TT>&#32;&#32;</TT> where ``nnn'' is replaced with the SCLK ID used to convert TDB to SCLK.
<BR><BR></UL>
<BR><BR>
<A NAME="Report Header for Coverage/Gaps for Two Orientations"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Report Header for Coverage/Gaps for Two Orientations
</H3><P><BR><BR>
   For runs displaying coverage or gaps in coverage for two orientations
   the report header has the following format (the line numbers given on
   the left are not present in the actual report; they are provided only
   for referencing purposes):
<P>
 
<PRE>
    1  #
    2  # Coverage overlap for rotation
    3  #
    4  #    from 'FROM1NAME' (FROM1ID) to 'TO1NAME' (TO1ID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # and rotation
   12  #
   13  #    from 'FROM2NAME' (FROM2ID) to 'TO2NAME' (TO2ID)
   14  #    computed using
   15  #
   16  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
   17  #       -K2/KERNEL1 -K2/KERNEL2 ... -K2/KERNELm
   18  #       SECONDKERNEL
   19  #
   20  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   21  # within the continuous time period
   22  #
   23  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   24  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   25  #
   26  # TIMESPEC.
   27  #
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> on lines 4 and 13 ``FROM1NAME'', ``FROM1ID'', ``TO1NAME'', ``TO1ID'',
``FROM2NAME'', ``FROM2ID'', ``TO2NAME'', and ``TO2ID'' are replaced with
the actual names/IDs used to compute transformations for comparison
<BR><BR></UL>
<UL>
<TT>--</TT> lines 7, 8, 9, 16, 17, and 18 contain lists of additional kernels provided
using the ``-k'', ``-k1'', and ``-k2'' keys and primary kernels provided at
the end of the command line, listed in the order in which they were loaded
by the program. These lines are present only when corresponding kernel
files are given on the command line.
<BR><BR></UL>
<UL>
<TT>--</TT> on line 20 the actual step replaces ``S'' and ``DDDAYS:HR:MN:SC.MSECND''
(step expressed as days, hours, minutes, seconds). If transformation is
computed only at the interval endpoints, the whole line is replaced with
the following string: ``at continuous coverage intervals' endpoints''.
<BR><BR></UL>
<UL>
<TT>--</TT> line 21 has the form shown above when there are no gaps in the coverage
window. Otherwise the whole line is replaced with the following string:
``within the non-continuous (with M gaps) time period'' where ``M'' is
replaced with the actual number of gaps.
<BR><BR></UL>
<UL>
<TT>--</TT> on lines 23 and 24 times are replaced with the first and last times from
the set of times for which the comparison was made.
<BR><BR></UL>
<UL>
<TT>--</TT> on line 26, depending on the output time type specified using the ``-f''
key, ``TIMESPEC'' is replaced with one of the following strings:
<BR><BR></UL>
<PRE>
            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID &lt;nnn&gt;.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '&lt;format&gt;' format.''
</PRE>
<UL>
<TT>&#32;&#32;</TT> where ``nnn'' is replaced with the SCLK ID used to convert TDB to SCLK.
<BR><BR></UL>
<BR><BR>
<A NAME="Report Header for Sampling an Orientation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Report Header for Sampling an Orientation
</H3><P><BR><BR>
   For runs sampling an orientation the report header has the following
   format (the line numbers given on the left are not present in the actual
   report; they are provided for referencing purposes only):
<P>
 
<PRE>
    1  #
    2  # Sampling of N rotations
    3  #
    4  #    from 'FROMNAME' (FROMID) to 'TONAME' (TOID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   12  # within the continuous time period
   13  #
   14  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   15  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   16  #
   17  # including angular velocities relative to the FRAME frame.
   18  #
   19  # TIMESPEC
   20  #
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> on line 2 ``N'' is replaced with the actual number of comparison points
<BR><BR></UL>
<UL>
<TT>--</TT> on line 4 ``FROMNAME'', ``FROMID'', ``TONAME'', and ``TOID'' are replaced
with the actual names/IDs used to compute transformations
<BR><BR></UL>
<UL>
<TT>--</TT> lines 7, 8, and 9 contain lists of additional kernels provided using ``-k''
and ``-k1'' (or ``-k2'') keys and the primary kernel provided at the end of
the command line, listed in the order in which they were loaded by the
program. These lines are present only when the corresponding kernel files
are given on the command line.
<BR><BR></UL>
<UL>
<TT>--</TT> on line 11 the actual step replaces ``S'' and ``DDDAYS:HR:MN:SC.MSECND''
(step expressed as days, hours, minutes, seconds). If transformation is
computed only at the interval endpoints, the whole line is replaced with
the following string: ``at continuous coverage intervals' endpoints''
<BR><BR></UL>
<UL>
<TT>--</TT> line 12 has the form shown above when there are no gaps in the coverage
window. Otherwise the whole line is replaced with the following string:
``within the non-continuous (with M gaps) time period'' where ``M'' is
replaced with the actual number of gaps.
<BR><BR></UL>
<UL>
<TT>--</TT> on lines 14 and 15 times are replaced with the first and last times from
the set of times for which transformation was computed.
<BR><BR></UL>
<UL>
<TT>--</TT> lines 17 and 18 are displayed only when angular velocities are computed.
The FRAME is set to ``from'' or ``to'' depending on the frame in which the
angular velocity is reported.
<BR><BR></UL>
<UL>
<TT>--</TT> line 19 and 20 are displayed for all report types except ``basic'' and
``stats''. Depending on the output time type specified using the ``-f'' key
TIMESPEC is replaced with one of the following strings:
<BR><BR></UL>
<PRE>
            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID &lt;nnn&gt;.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '&lt;format&gt;' format.''
</PRE>
<UL>
<TT>&#32;&#32;</TT> where ``nnn'' is replaced with the SCLK ID used to convert TDB to SCLK.
<BR><BR></UL>
<BR><BR>
<A NAME="Report Header for Coverage/Gaps for An Orientation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Report Header for Coverage/Gaps for An Orientation
</H3><P><BR><BR>
   For runs displaying coverage or gaps in coverage for an orientation the
   report header has the following format (the line numbers given on the
   left are not present in the actual report; they are provided for
   referencing purposes only):
<P>
 
<PRE>
    1  #
    2  # Coverage for rotation
    3  #
    4  #    from 'FROMNAME' (FROMID) to 'TONAME' (TOID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   12  # within the continuous time period
   13  #
   14  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   15  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   16  #
   17  # TIMESPEC
   18  #
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> on line 4 ``FROMNAME'', ``FROMID'', ``TONAME'', and ``TOID'' are replaced
with the actual names/IDs used to compute transformations.
<BR><BR></UL>
<UL>
<TT>--</TT> lines 7, 8, and 9 contain lists of additional kernels provided using the
``-k'' and ``-k1'' (or ``-k2'') keys and the primary kernel provided at the
end of the command line, listed in the order in which they were loaded by
the program. These lines are present only when the corresponding the kernel
files are given on the command line.
<BR><BR></UL>
<UL>
<TT>--</TT> on line 11 the actual step replaces ``S'' and ``DDDAYS:HR:MN:SC.MSECND''
(step expressed as days, hours, minutes, seconds). If transformation is
computed only at the interval endpoints, the whole line is replaced with
the following string: ``at continuous coverage intervals' endpoints''
<BR><BR></UL>
<UL>
<TT>--</TT> line 12 has the form shown above when there are no gaps in the coverage
window. Otherwise the whole line is replaced with the following string:
``within the non-continuous (with M gaps) time period'' where ``M'' is
replaced with the actual number of gaps.
<BR><BR></UL>
<UL>
<TT>--</TT> on lines 14 and 15 times are replaced with the first and last times from
the set of times for which transformation was computed.
<BR><BR></UL>
<UL>
<TT>--</TT> on line 17, depending on the output time type specified using the ``-f''
key TIMESPEC is replaced with one of the following strings:
<BR><BR></UL>
<PRE>
            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID &lt;nnn&gt;.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID &lt;nnn&gt;.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '&lt;format&gt;' format.''
</PRE>
<UL>
<TT>&#32;&#32;</TT> where ``nnn'' is replaced with the SCLK ID used to convert TDB to SCLK.
<BR><BR></UL>
<BR><BR>
<A NAME="Report Formats"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Report Formats
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="Basic Report (no ``-t'' or ``-t basic'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Basic Report (no ``-t'' or ``-t basic'')
</H3><P><BR><BR>
   The basic report indicates if the two frame transformations are
   different, or if a single transformation is a non-zero transformation,
   by displaying only the maximum and the average rotation angle difference
   (for comparison runs) or rotation angle (for sampling runs) and, if
   requested using the ``-a'' key, the maximum and the average angular
   velocity magnitude difference (for comparison runs) or angular velocity
   magnitude (for sampling runs).
<P>
 
   The basic report has the following format:
<P>
 
<PRE>
 
   Absolute difference magnitudes:
 
                                       maximum             average
 
     Rotation (rad):                  MAX_ANGLE         AVERAGE_ANGLE
     Angular Velocity (rad/s):        MAX_RATE          AVERAGE_RATE
 
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> ``MAX_ANGLE'', ``AVERAGE_ANGLE'', ``MAX_RATE'', ``AVERAGE_RATE'' are the
maximum and average rotation angle difference (for comparison runs) or
angle (for sampling runs) and angular velocity difference (for comparison
runs) or angular velocity magnitude (for sampling runs) determined for the
set of frame transformation differences or frame transformations computed
by the program within the coverage window.
<BR><BR></UL>
<UL>
<TT>--</TT> The word ``difference'' is omitted from the ``Absolute difference
magnitudes:'' line when the program is run in sampling mode.
<BR><BR></UL>
<UL>
<TT>--</TT> The line ``Angular Velocity ...'' is omitted when AVs are not
compared/sampled (no ``-a'' or ``-a no'').
<BR><BR></UL>
<UL>
<TT>--</TT> All ``*ANGLE'' and ``*RATE'' values are printed in the
``x.xxxxxxxxxxxxxE+xx'' format.
<BR><BR></UL>
<UL>
<TT>--</TT> All ``*ANGLE'' values are always printed in radians (i.e. units specified
using the ``-x'' key have no effect on the values in this report).
<BR><BR></UL>
<UL>
<TT>--</TT> All ``*RATE'' values are always printed in radians per second.
<BR><BR></UL>
<BR><BR>
<A NAME="Statistics Report (``-t stats'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Statistics Report (``-t stats'')
</H3><P><BR><BR>
   The statistics report provides a small set of statistical information on
   the difference of two frame transformations (for comparison runs) or a
   single transformation (for sampling runs). It includes the same items as
   the basic report (maximums and averages) plus a few additional
   parameters such as RMS of the rotation angle difference/angle and
   angular velocity difference/angular velocity and the times when the
   maximum value of the rotation angle difference/angle and angular
   velocity difference/angular velocity were found.
<P>
 
   The statistics report has the following format:
<P>
 
<PRE>
 
   1) Average difference
 
      1a) Rotation (rad):                               AVERAGE_ANGLE
 
      1b) Angular velocity (rad/s):                     AVERAGE_RATE
 
 
   2) RMS of difference
 
      2a) Rotation (rad):                               RMS_OF_ANGLE
 
      2b) Angular velocity (rad/s):                     RMS_OF_RATE
 
 
   3) Maximum rotation difference
 
      3a) Rotation (rad):                               MAX_ANGLE
 
      3b) Epoch (TDB, seconds past J2000):              TDB_SECONDS
 
      3c) Epoch (TDB, calendar format):         YYYY-MON-DD-HR:MN:SC.MMM
 
 
   4) Maximum angular velocity difference
 
      4a) Angular velocity (rad/s):                     MAX_RATE
 
      4b) Epoch (TDB, seconds past J2000):              TDB_SECONDS
 
      4c) Epoch (TDB, calendar format):         YYYY-MON-DD-HR:MN:SC.MMM
 
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> ``MAX_ANGLE'', ``AVERAGE_ANGLE'', ``RMS_OF_ANGLE'', ``MAX_RATE'',
``AVERAGE_RATE'', ``RMS_OF_RATE'' are the maximum, average, and RMS of
rotation angle difference (for comparison runs) or angle (for sampling
runs) and angular velocity difference (for comparison runs) or angular
velocity magnitude (for sampling runs) determined for the set of frame
transformation differences or frame transformations computed by the program
within the coverage window. ``TDB_SECONDS'' and
``YYYY-MON-DD-HR:MN:SC.MMM'' are the times, as TDB seconds past J2000 and
TDB in calendar date format, when the maximums were found.
<BR><BR></UL>
<UL>
<TT>--</TT> The word ``difference'' is omitted from the lines starting with ``1)'',
``2)'', ``3)'', and ``4)'' when the program is run in sampling mode.
<BR><BR></UL>
<UL>
<TT>--</TT> All lines pertaining to angular velocity are omitted when AVs are not
compared/sampled (no ``-a'' or ``-a no'').
<BR><BR></UL>
<UL>
<TT>--</TT> All ``*ANGLE'' and ``*RATE'' values are printed in ``x.xxxxxxxxxxxxxE+xx''
format.
<BR><BR></UL>
<UL>
<TT>--</TT> All ``*ANGLE'' values are always printed in radians (i.e. units specified
using the ``-x'' key have no effect on the values in this report).
<BR><BR></UL>
<UL>
<TT>--</TT> All ``*RATE'' values are always printed in radians per second.
<BR><BR></UL>
<UL>
<TT>--</TT> ``TDB_SECONDS'' are printed in the ``xxxxxxxxxx.xxxxxx'' format.
<BR><BR></UL>
<BR><BR>
<A NAME="Angle and Axis Dump Report (``-t dumpaa'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Angle and Axis Dump Report (``-t dumpaa'')
</H3><P><BR><BR>
   The angle and axis dump report displays the orientation difference (for
   comparison runs) or orientation (for sampling runs) expressed as the
   rotation angle and axis and, if requested using the ``-a'' key, the
   components and the magnitude of the angular velocity difference (for
   comparison runs) or angular velocity (for sampling runs), along with the
   time, for each of the times at which the frame transformations were
   computed. The angle is displayed in units specified using the ``-x'' key
   -- ``radians'' (default), ``degrees'', ``arcminutes'', ``arcseconds'',
   ``hourangle'', ``minuteangle'', or ``secondangle''. The time tags are
   displayed in the format specified using the ``-f'' key, discussed
   earlier in this document.
<P>
 
   The angle and axis dump report has the following format:
<P>
 
<PRE>
   # angle is shown in UNITS.
   #
   # time, angle, axis_x, axis_y, axis_z, av_x, av_y, av_z, av_magnitude
   TIME ANGLE AXIS(1) AXIS(2) AXIS(3) AV(1) AV(2) AV(3) |AV|
   ...
   TIME ANGLE AXIS(1) AXIS(2) AXIS(3) AV(1) AV(2) AV(3) |AV|
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> All items except TIME are printed in the ``x.xxxxxxxxxxxxxE+xx'' format.
TIME is displayed in the format specified using the ``-f'' key.
<BR><BR></UL>
<UL>
<TT>--</TT> The ANGLE is displayed in units specified using the ``-x'' key. The AV
components and magnitude are always displayed in radians per second.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV difference/AV components and the corresponding labels in the table
header line are omitted when AVs are not compared/sampled (no ``-a'' or
``-a no'').
<BR><BR></UL>
<UL>
<TT>--</TT> UNITS is replaced with the units used to display the angles.
<BR><BR></UL>
<BR><BR>
<A NAME="Matrix Dump Report (``-t dumpm'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Matrix Dump Report (``-t dumpm'')
</H3><P><BR><BR>
   The matrix dump report displays the orientation difference (for
   comparison runs) or orientation (for sampling runs) expressed as a 3x3
   rotation matrix and, if requested using the ``-a'' key, the components
   of the angular velocity difference (for comparison runs) or angular
   velocity (for sampling runs), along with the time, for each of the times
   at which the frame transformations were computed. The time tags are
   displayed in the format specified using the ``-f'' key, discussed
   earlier in this document.
<P>
 
   The matrix dump report has the following format:
<P>
 
<PRE>
   # time, m11, m12, m13, m21, m22, m23, m31, m32, m33, av_x, av_y, av_z
   TIME M11 M12 M13 M21 M22 M23 M31 M32 M33 AV(1) AV(2) AV(3)
   ...
   TIME M11 M12 M13 M21 M22 M23 M31 M32 M33 AV(1) AV(2) AV(3)
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> All items except TIME are printed in the ``x.xxxxxxxxxxxxxE+xx'' format.
TIME is displayed in the format specified using the ``-f'' key.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV components are always displayed in radians per second.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV difference/AV components and the corresponding labels in the table
header line are omitted when AVs are not compared/sampled (no ``-a'' or
``-a no'').
<BR><BR></UL>
<BR><BR>
<A NAME="SPICE-Style Quaternion Dump Report (``-t dumpqs'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> SPICE-Style Quaternion Dump Report (``-t dumpqs'')
</H3><P><BR><BR>
   The SPICE-style quaternion dump report displays the orientation
   difference (for comparison runs) or orientation (for sampling runs)
   expressed as a SPICE-style quaternion and, if requested using the ``-a''
   key, the components of the angular velocity difference (for comparison
   runs) or angular velocity (for sampling runs), along with the time, for
   each of the times at which the frame transformations were computed. The
   time tag is displayed in the format specified using the ``-f'' key,
   discussed earlier in this document.
<P>
 
   The SPICE-style quaternion dump report has the following format:
<P>
 
<PRE>
   # time, q_cos, q_sin1, q_sin2, q_sin3, av_x, av_y, av_z
   TIME QS(1) QS(2) QS(3) QS(4) AV(1) AV(2) AV(3)
   ...
   TIME QS(1) QS(2) QS(3) QS(4) AV(1) AV(2) AV(3)
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> All items except TIME are printed in the ``x.xxxxxxxxxxxxxE+xx'' format.
TIME is displayed in the format specified using the ``-f'' key.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV components are always displayed in radians per second.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV difference/AV components and the corresponding labels in the table
header line are omitted when AVs are not compared/sampled (no ``-a'' or
``-a no'').
<BR><BR></UL>
<BR><BR>
<A NAME="``Other''-Style Quaternion Dump Report (``-t dumpqo'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> ``Other''-Style Quaternion Dump Report (``-t dumpqo'')
</H3><P><BR><BR>
   The ``other''-style quaternion dump report displays the orientation
   difference (for comparison runs) or orientation (for sampling runs)
   expressed as the ``other''-style (or engineering-style) quaternion and,
   if requested using the ``-a'' key, the components of the angular
   velocity difference (for comparison runs) or angular velocity (for
   sampling reports), along with the time, for each of the times at which
   frame transformations were computed. The time tags are displayed in the
   format specified using the ``-f'' key, discussed earlier in the
   document.
<P>
 
   The ``other''-style quaternion dump report has the following format:
<P>
 
<PRE>
   # time, q_sin1, q_sin2, q_sin3, q_cos, av_x, av_y, av_z
   TIME QO(1) QO(2) QO(3) QO(4) AV(1) AV(2) AV(3)
   ...
   TIME QO(1) QO(2) QO(3) QO(4) AV(1) AV(2) AV(3)
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> All items except TIME are printed in the ``x.xxxxxxxxxxxxxE+xx'' format.
TIME is displayed in the format specified using the ``-f'' key.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV components are always displayed in radians per second.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV difference/AV components and the corresponding labels in the table
header line are omitted when AVs are not compared/sampled (no ``-a'' or
``-a no'').
<BR><BR></UL>
<BR><BR>
<A NAME="Euler Angles Dump Report (``-t dumpea'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Euler Angles Dump Report (``-t dumpea'')
</H3><P><BR><BR>
   The Euler angles dump report displays the orientation difference (for
   comparison runs) or orientation (for sampling runs) expressed as three
   Euler angles and, if requested using the ``-a'' key, the components of
   the angular velocity difference (for comparison runs) or angular
   velocity (for sampling runs), along with the time, for each of the times
   at which frame transformations were computed. The order of rotations is
   specified using the ``-o'' key as sequence of three axes from the set of
   ``X'', ``Y'', ``Z'' (case-insensitive), separated by spaces. The second
   axis in the sequence must differ from the first and third axes. When
   ``-o'' is not provided, the default order is set to ``Z Y X''. The
   angles are displayed in the units specified using the ``-x'' key --
   ``radians'' (default), ``degrees'', ``arcminutes'', ``arcseconds'',
   ``hourangle'', ``minuteangle'', or ``secondangle''. The time tags are
   displayed in the format specified using the ``-f'' key, discussed
   earlier in this document.
<P>
 
   The Euler angles dump report has the following format:
<P>
 
<PRE>
   # angles are shown in UNITS
   #
   # time, angle_AXIS3, angle_AXIS2, angle_AXIS1, av_x, av_y, av_z
   TIME ANGLE3 ANGLE2 ANGLE1 AV(1) AV(2) AV(3)
   ...
   TIME ANGLE3 ANGLE2 ANGLE1 AV(1) AV(2) AV(3)
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> All items except TIME are printed in the ``x.xxxxxxxxxxxxxE+xx'' format.
TIME is displayed in the format specified using the ``-f'' key.
<BR><BR></UL>
<UL>
<TT>--</TT> The ANGLEs are displayed in the units specified using the ``-x'' key. The
AV components are always displayed in radians per second.
<BR><BR></UL>
<UL>
<TT>--</TT> The AV difference/AV components and the corresponding labels in the table
header line are omitted when AVs are not compared/sampled (no ``-a'' or
``-a no'').
<BR><BR></UL>
<UL>
<TT>--</TT> UNITS is replaced with the units used to display angles.
<BR><BR></UL>
<UL>
<TT>--</TT> ``AXIS1'', ``AXIS2'', ``AXIS3'' are replaced with the corresponding axis
labels (X,Y, or Z).
<BR><BR></UL>
<BR><BR>
<A NAME="Coverage Intervals Dump Report (``-t dumpc''):"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Coverage Intervals Dump Report (``-t dumpc''):
</H3><P><BR><BR>
   The coverage intervals dump report displays the start and stop times for
   the intervals inside the coverage window, during which frame
   transformations can be computed. The time tags are displayed in the
   format specified using the ``-f'' key, discussed earlier in the
   document.
<P>
 
   The coverage intervals dump report has the following format:
<P>
 
<PRE>
   # int_start_time, int_end_time, int_duration_sec, int_duration_string
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
   ...
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
</PRE>
   where:
<P>
 
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> The interval durations are printed as seconds in the
``x.xxxxxxxxxxxxxE+xx'' format (replaces SECONDS) and in days, hours,
minutes, seconds format (replaces DAYS:HR:MN:SC.MMMMMM). The STARTTIMEs and
STOPTIMEs are displayed in the format specified using the ``-f'' key.
<BR><BR></UL>
<BR><BR>
<A NAME="Coverage Gaps Dump Report (``-t dumpg'')"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Coverage Gaps Dump Report (``-t dumpg'')
</H3><P><BR><BR>
   The coverage gaps dump report displays the start and stop times for the
   gaps inside the coverage window, during which frame transformations
   cannot be computed. The time tags are displayed in the format specified
   using the ``-f'' key, discussed earlier in this document.
<P>
 
   The coverage gaps dump report has the following format:
<P>
 
<PRE>
   # gap_start_time, gap_end_time, gap_duration_sec, gap_duration_string
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
   ...
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
</PRE>
<UL>
<TT>--</TT> Items on each data line are separated by spaces.
<BR><BR></UL>
<UL>
<TT>--</TT> The gap durations are printed as seconds in the ``x.xxxxxxxxxxxxxE+xx''
format (replaces SECONDS) and in days, hours, minutes, seconds format
(replaces DAYS:HR:MN:SC.MMMMMM). The STARTTIMEs and STOPTIMEs are displayed
in the format specified using the ``-f'' key.
<BR><BR></UL>
<UL>
<TT>--</TT> If the coverage window has no gaps, the string ``There are no gaps in
coverage.'' is printed instead of the data records.
<BR><BR></UL>
<BR><BR>
<A NAME="Examples"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Examples
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   The examples below illustrate some of the common FRMDIFF usage
   scenarios. In all examples the files are assumed to be in the current
   directory, the FRMDIFF command lines, which usually occupy a single
   line, span multiple lines and use the UNIX shell style continuation
   character (backslash), and the report lines are truncated to fit the
   width of the page (``...'' at the end of a line indicates that it was
   truncated).
<P>
 
<BR><BR>
<A NAME="Checking if Two CKs Provide the Same Orientation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Checking if Two CKs Provide the Same Orientation
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to check if the daily reconstructed
   MRO CK ``mro_sc_2009-01-26.bc'' and the weekly reconstructed MRO CK
   ``mro_sc_psp_090120_090126.bc'' provide the same data. The CK files are
   provided as primary kernels to make the program run in comparison mode.
   The LSK ``naif0009.tls'' and SCLK ``MRO_SCLKSCET.00027.tsc'', required
   to support time conversions, and the FK ``mro_v13.tf'', required because
   it defines the MRO spacecraft frame and the frame used as the base frame
   in the CKs, apply to both CKs and, therefore, are provided using the
   ``-k'' key. To make sure the comparison is thorough the step is set to 1
   second using the ``-s'' key. No other options need to be specified
   because the primary kernels are CKs, which the program can examine to
   automatically pick the ``from'' and ``to'' frames and the coverage
   window. The basic report displaying the maximum difference will suffice
   for this case; therefore, there is no need to specify the ``-t'' option.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls MRO_SCLKSCET.00027.tsc mro_v13.tf \
             -s 1 \
             mro_sc_2009-01-26.bc mro_sc_psp_090120_090126.bc
   # int_start_time, int_end_time, int_duration_sec, int_duration_string
   #
   # Comparison of 86401 rotations
   #
   #    from 'MRO_MME_OF_DATE' (-74900) to 'MRO_SPACECRAFT' (-74000)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.tsc mro_v13.tf
   #       mro_sc_2009-01-26.bc
   #
   # with 86401 rotations
   #
   #    from 'MRO_MME_OF_DATE' (-74900) to 'MRO_SPACECRAFT' (-74000)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.tsc mro_v13.tf
   #       mro_sc_psp_090120_090126.bc
   #
   # with a 1.0000000000000 second (0:00:00:01.000000) step size
   # within the continuous time period
   #
   #    from '2009 JAN 26 00:01:06.261' TDB (286200066.26113 TDB seco...
   #    to   '2009 JAN 27 00:01:06.024' TDB (286286466.02413 TDB seco...
   #
 
   Absolute difference magnitudes:
 
                                        maximum                 avera...
 
     Rotation (rad):             +0.0000000000000E+00      +0.0000000...
 
</PRE>
   The zero maximum rotation difference indicates that these two CKs
   provide the same data.
<P>
 
<BR><BR>
<A NAME="Comparing Predicted and Reconstructed CKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Comparing Predicted and Reconstructed CKs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to assess, for a specified period of
   time, the difference of the spacecraft orientation provided by the
   predicted CASSINI spacecraft CK ``09009_09025pa_fsiv_lud2.bc'' and the
   reconstructed CASSINI spacecraft CK ``09006_09011ra.bc''. The CK files
   are provided as primary kernels to make the program run in comparison
   mode. The LSK ``naif0009.tls'' and the SCLK ``cas00130.tsc'', required
   to support time conversions, and the FK ``cas_v40.tf'', required because
   it defines the CASSINI spacecraft frame, apply to both CKs and,
   therefore, are provided using the ``-k'' key. The angle and axis dump
   report is requested using ``-t dumpaa'' and the step is set to 10
   seconds using ``-s 10''. The time boundaries for the period of interest
   are specified using ``-b'' and ``-e''. No other options need to be
   specified because the primary kernels are CKs, which the program can
   examine to automatically pick the ``from'' and ``to'' frames and the
   default coverage window (which is intersected with the window of
   interest specified using ``-b'' and ``-e''). The program's output is
   re-directed to the file ``output.txt'' using the ``&gt;'' shell pipe,
   with the contents of the file shown using the UNIX ``cat'' command.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls cas00130.tsc cas_v40.tf \
             -s 10 -b 2009-JAN-09 00:00 -e 2009-JAN-10 00:00 -t dumpaa \
             09009_09025pa_fsiv_lud2.bc 09006_09011ra.bc \
             &gt; output.txt
   % cat output.txt
   #
   # Comparison of 3143 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09009_09025pa_fsiv_lud2.bc
   #
   # with 3143 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09006_09011ra.bc
   #
   # with a 10.000000000000 second (0:00:00:10.000000) step size
   # within the non-continuous (with 1 gaps) time period
   #
   #    from '2009 JAN 09 15:17:06.359' TDB (284786226.35996 TDB seco...
   #    to   '2009 JAN 10 00:01:06.184' TDB (284817666.18419 TDB seco...
   #
   # Times are TDB seconds past J2000.
   #
   # angle is shown in radians.
   #
   # time, angle, axis_x, axis_y, axis_z
   +2.8478622635996E+08 +5.4958832051797E-05 +8.2101753099566E-01 +4....
   +2.8478623635996E+08 +5.4931030131424E-05 +8.2046010733260E-01 +4....
   +2.8478624635996E+08 +5.4903290577181E-05 +8.1990116349661E-01 +4....
   ...
   +2.8481765833081E+08 +2.3714852496640E-05 +4.7607884330795E-01 -8....
   +2.8481766618419E+08 +1.7506382825421E-05 -3.3218433215999E-01 -6....
</PRE>
   The orientation difference expressed as the rotation angle (column 2)
   can be plotted against TDB seconds (column 1) for analysis.
<P>
 
   Note that the time window shown in the report header is different from
   the requested window specified using the ``-b'' and ``-e'' options. The
   reason for that is the lack of coverage for the requested windows in one
   of the CKs (``09009_09025pa_fsiv_lud2.bc'').
<P>
 
   To find out when the difference between two orientations is the greatest
   without plotting the difference as suggested above, the program can be
   re-run with the same options to generate a statistics report (``-t
   stats''). For such a run it makes sense to also decrease the time step
   in order to determine the time of interest more accurately, for example
   by setting the step to 1 second (``-s 1'').
<P>
 
<PRE>
   % frmdiff -k naif0009.tls cas00130.tsc cas_v40.tf \
             -s 1 -b 2009-JAN-09 00:00 -e 2009-JAN-10 00:00 -t stats \
             09009_09025pa_fsiv_lud2.bc 09006_09011ra.bc
   #
   # Comparison of 31414 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09009_09025pa_fsiv_lud2.bc
   #
   # with 31414 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09006_09011ra.bc
   #
   # with a 1.0000000000000 second (0:00:00:01.000000) step size
   # within the non-continuous (with 1 gaps) time period
   #
   #    from '2009 JAN 09 15:17:06.359' TDB (284786226.35996 TDB seco...
   #    to   '2009 JAN 10 00:01:06.184' TDB (284817666.18419 TDB seco...
   #
 
   1) Average difference
 
      1a) Rotation (rad):                               0.00007738559...
 
 
   2) RMS of difference
 
      2a) Rotation (rad):                               0.00016380723...
 
 
   3) Maximum rotation difference
 
      3a) Rotation (rad):                               0.00098956656...
 
      3b) Epoch (TDB, seconds past J2000):              284788762.33081
 
      3c) Epoch (TDB, calendar format):         2009-JAN-09-15:59:22.330
 
</PRE>
   As seen in the report the maximum difference between orientations
   provided by these CKs between 2009-JAN-09 15:17:06 TDB and 2009-JAN-10
   00:01:06 TDB is about 1 milliradian near 2009-JAN-09 15:59:22 TDB.
<P>
 
<BR><BR>
<A NAME="Comparing Orientations from a CK Read Using Different SCLKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Comparing Orientations from a CK Read Using Different SCLKs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to assess the effect that using an
   out-of-date SCLK kernel has on the 2001 Mars Odyssey spacecraft
   orientation computed from the M01 CK file ``m01_sc_2009-01-27.bc''. To
   make the program run in comparison mode, the current SCLK
   ``ORB1_SCLKSCET.00157.tsc'' and the out-of-date SCLK
   ``ORB1_SCLKSCET.00147.tsc'' are provided using the ``-k1'' and ``-k2''
   keys while the CK is provided as the only primary kernel.
   (Alternatively, the SCLK kernels could be provided as two primary
   kernels while the CK could be provided using the ``-k'' key, in which
   case the ``from'' and ``to'' frames and the coverage boundaries would
   have to be specified because the program would not be able to determine
   defaults from the SCLK kernels.) The LSK ``naif0009.tls'', required to
   support time conversions, and the FK ``m01_v28.tf'', required because it
   defines the M01 spacecraft frame, are provided using the ``-k'' key. The
   angle and axis dump report is requested using ``-t dumpaa'' and the step
   size is set to 10 seconds using ``-s 10''. No other options need to be
   specified because the primary kernel is a CK, which the program can
   examine to automatically pick the ``from'' and ``to'' frames and the
   default coverage window. The program's output is re-directed to the file
   ``output.txt'' using the ``&gt;'' shell pipe, with the contents of the
   file shown using the UNIX ``cat'' command.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls m01_v28.tf \
             -k1 ORB1_SCLKSCET.00157.tsc \
             -k2 ORB1_SCLKSCET.00147.tsc \
             -s 10 -t dumpaa \
             m01_sc_2009-01-27.bc \
             &gt; output.txt
   % cat output.txt
   #
   # Comparison of 8283 rotations
   #
   #    from 'MARSIAU' (16) to 'M01_SPACECRAFT' (-53000)
   #    computed using
   #
   #       naif0009.tls m01_v28.tf
   #       ORB1_SCLKSCET.00157.tsc
   #       m01_sc_2009-01-27.bc
   #
   # with 8283 rotations
   #
   #    from 'MARSIAU' (16) to 'M01_SPACECRAFT' (-53000)
   #    computed using
   #
   #       naif0009.tls m01_v28.tf
   #       ORB1_SCLKSCET.00147.tsc
   #       m01_sc_2009-01-27.bc
   #
   # with a 10.000000000000 second (0:00:00:10.000000) step size
   # within the non-continuous (with 2 gaps) time period
   #
   #    from '2009 JAN 27 00:01:07.301' TDB (286286467.30114 TDB seco...
   #    to   '2009 JAN 28 00:01:03.083' TDB (286372863.08345 TDB seco...
   #
   # Times are TDB seconds past J2000.
   #
   # angle is shown in radians.
   #
   # time, angle, axis_x, axis_y, axis_z
   +2.8628646730114E+08 +1.6811778261922E-04 -1.6518133891799E-03 -1....
   +2.8628647730114E+08 +1.6807590586987E-04 -2.5417591048513E-03 -9....
   ...
   +2.8637285336657E+08 +1.5490156847677E-04 -1.0767849826583E-03 -1....
   +2.8637286308345E+08 +1.5459290844816E-04 +5.3342008940173E-05 +1....
</PRE>
   The orientation difference expressed as rotation angle (column 2) can be
   plotted against TDB seconds (column 1) for analysis.
<P>
 
<BR><BR>
<A NAME="Comparing Binary and Text PCKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Comparing Binary and Text PCKs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to compare Earth orientations
   provided by the high precision Earth orientation binary PCK file
   ``earth_000101_090421_090128.bpc'' and the low precision Earth
   orientation text PCK file ``pck00008.tpc''. The PCK files are specified
   as two primary kernels to make the program run in comparison mode. For
   this run both ``to'' frames must be specified because the frame
   associated with the high precision orientation -- ``ITRF93'' -- is
   different from the frame associated with the low precision orientation
   -- ``IAU_EARTH''. These two frames are provided using the ``-t1'' and
   ``-t2'' keys. Note that neither the coverage boundaries nor the ``from''
   frames need to be specified because the program can set them to default
   values obtained by examining the binary PCK. The step is set to 1 hour
   (``-s 3600'') and the report type is picked to be the Euler angle dump
   (``-t dumpea'') with the rotation axis order Z,Y,X (``-o z y x'').
   Reporting differences as Euler angles might be desirable in this case
   because the angles will show how much of the difference is in the pole
   tilt (combination of angles about X and Y) and how much of it is in the
   rotation about the pole (angle about Z). The ``-x'' option used to
   report angles in degrees (``-x degrees''). The program's output is
   re-directed to the file ``output.txt'' using the ``&gt;'' shell pipe,
   with the contents of the file shown using the UNIX ``cat'' command.
<P>
 
<PRE>
   % frmdiff -t1 ITRF93 -t2 IAU_EARTH \
             -s 3600 -t dumpea -o Z Y X -x degrees \
             earth_000101_090421_090128.bpc pck00008.tpc \
             &gt; output.txt
   % cat output.txt
   #
   # Comparison of 81553 rotations
   #
   #    from 'ECLIPJ2000' (17) to 'ITRF93' (13000)
   #    computed using
   #
   #       earth_000101_090421_090128.bpc
   #
   # with 81553 rotations
   #
   #    from 'ECLIPJ2000' (17) to 'IAU_EARTH' (10013)
   #    computed using
   #
   #       pck00008.tpc
   #
   # with a 3600.0000000000 second (0:01:00:00.000000) step size
   # within the continuous time period
   #
   #    from '2000 JAN 01 00:01:04.183' TDB (-43135.816087188 TDB sec...
   #    to   '2009 APR 21 00:01:06.185' TDB (293544066.18557 TDB seco...
   #
   # Times are TDB seconds past J2000.
   #
   # angles are shown in degrees.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   -4.3135816087188E+04 +4.6935841900452E-02 -1.3237283886873E-03 -1....
   -3.9535816087188E+04 +4.6935945731300E-02 -8.1268845525487E-04 -2....
   ...
   +2.9354046418391E+08 +5.9885369786058E-02 -1.7263299596662E-03 +1....
   +2.9354406618557E+08 +5.9885381660130E-02 -1.9758128919827E-03 +5....
</PRE>
   The Euler angles about Z, Y, and X (column 2, 3, 4) can be plotted
   against TDB seconds (column 1) for analysis.
<P>
 
<BR><BR>
<A NAME="Comparing Two Text PCKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Comparing Two Text PCKs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to compare Mars orientations provided
   by the text PCK file ``pck00006.tpc'' containing 1994 IAU constants and
   the text PCK ``pck00008.tpc'' containing IAU 2000 constants. The PCK
   files are specified as two primary kernels to make the program run in
   comparison mode. Since both files are neither CKs nor binary PCKs, the
   ``from'' and ``to'' frames and the time boundaries for coverage window
   must be specified using the ``-t1'' (or ``-t2''), ``-f1'' (or ``-f2''),
   and ``-b'' and ``-e'' keys. Since the time boundaries are provided on
   the command line, the LSK ``naif0009.tls'' required for time conversions
   must be provided using ``-k'' (either ``-k1'' or ``-k2'' can also be
   used). The step is set to 1 hour (``-s 3600'') and the report type is
   picked to be the Euler angles dump (``-t dumpea'') with the rotation
   axis order Z,Y,X (``-o z y x''). Reporting differences as Euler angles
   might be desirable in this case because the angles will show how much of
   the difference is in the pole tilt (combination of angles about X and Y)
   and how much of it is in the rotation about the pole (angle about Z).
   The ``-x'' option is used to report angles in degrees (``-x degrees'').
   The ``-f'' option is used to print times as UTC in ISO date format (``-f
   YYYY-MM-DDTHR:MN:SC ::RND''). The program's output is re-directed to the
   file ``output.txt'' using the ``&gt;'' shell pipe, with the contents of
   the file shown using the UNIX ``cat'' command.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls -f1 J2000 -t1 IAU_MARS \
             -b 2005-01-01 -e 2006-01-01 \
             -t dumpea -o z y x -x degrees \
             -f YYYY-MM-DDTHR:MN:SC ::RND -s 3600 \
             pck00006.tpc pck00008.tpc \
             &gt; output.txt
   % cat output.txt
   #
   # Comparison of 8761 rotations
   #
   #    from 'J2000' (1) to 'IAU_MARS' (10014)
   #    computed using
   #
   #       naif0009.tls
   #       pck00006.tpc
   #
   # with 8761 rotations
   #
   #    from 'J2000' (1) to 'IAU_MARS' (10014)
   #    computed using
   #
   #       naif0009.tls
   #       pck00008.tpc
   #
   # with a 3600.0000000000 second (0:01:00:00.000000) step size
   # within the continuous time period
   #
   #    from '2005 JAN 01 00:01:04.183' TDB (157809664.18393 TDB seco...
   #    to   '2006 JAN 01 00:01:05.183' TDB (189345665.18393 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC ::RND'...
   #
   # angles are shown in degrees.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   2005-01-01T00:00:00 +2.7193295981800E-01 +4.3458477098658E-04 +4.0...
   2005-01-01T01:00:00 +2.7193298908895E-01 +3.1750496671468E-04 +5.0...
   ...
   2005-12-31T23:00:00 +2.7218789688912E-01 +3.4616175147429E-04 -4.9...
   2006-01-01T00:00:00 +2.7218792598016E-01 +4.5965878416891E-04 -3.9...
</PRE>
   The Euler angles about Z, Y, and X (column 2, 3, 4) can be plotted
   against UTC (column 1) for analysis.
<P>
 
<BR><BR>
<A NAME="Sampling Orientation from a CK"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Sampling Orientation from a CK
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to sample the orientation and angular
   velocity of Deep Impact Flyby (DIF) spacecraft from the daily CK
   ``dif_sc_2009-01-27.bc'' every five seconds over the whole period
   covered by the file and and print the orientation as engineering style
   quaternions and angular velocities expressed in the spacecraft frame,
   tagged with DP SCLKs. In addition to the CK file the LSK
   ``naif0009.tls'' and SCLK ``DIF_SCLKSCET.00036.tsc'', required to
   support time conversions, and the FK ``di_v17.tf'', required because it
   defines the DIF spacecraft frame, must be provided to the program. The
   CK file is provided as the only primary kernel and all other kernels are
   provided using ``-k'' to make the program run in sampling mode. The step
   is set to 5 seconds using ``-s 5''. The report type is set to the
   ``other''-style quaternion dump using ``-t dumpqo''. The output time
   format is set to DP SCLK using ``-f sclkd''. ``-a yes'' and ``-m to''
   are specified to add angular velocities rotated to the spacecraft frame
   (the ``to'' frame) to the output. No other options need to be specified
   because the primary kernel is a CK, which the program can examine to
   automatically pick the ``from'' and ``to'' frames and the coverage
   window. The program's output is re-directed to the file ``output.txt''
   using the ``&gt;'' shell pipe, with the contents of the file shown using
   the UNIX ``cat'' command.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls DIF_SCLKSCET.00036.tsc di_v17.tf \
             -s 5 -t dumpqo -f sclkd -a yes -m to \
             dif_sc_2009-01-27.bc \
             &gt; output.txt
   % cat output.txt
   #
   # Sampling of 16864 rotations
   #
   #    from 'J2000' (1) to 'DIF_SPACECRAFT' (-140000)
   #    computed using
   #
   #       naif0009.tls DIF_SCLKSCET.00036.tsc di_v17.tf
   #       dif_sc_2009-01-27.bc
   #
   # with a 5.0000000000000 second (0:00:00:05.000000) step size
   # within the non-continuous (with 2 gaps) time period
   #
   #    from '2009 JAN 27 00:01:06.713' TDB (286286466.71354 TDB seco...
   #    to   '2009 JAN 28 00:01:05.346' TDB (286372865.34683 TDB seco...
   #
   # including angular velocities relative to 'to' frame.
   #
   # Times are decimal SCLKs computed using SCLK ID -140.
   #
   # time, q_sin1, q_sin2, q_sin3, q_cos, av_x, av_y, av_z
   2.8628543276953E+08 +6.9350853049532E-01 +3.7594179111024E-01 -6.1...
   2.8628543776953E+08 +6.9350851552324E-01 +3.7594215798843E-01 -6.1...
   ...
   2.8637182501172E+08 +6.9259444035804E-01 +3.8202205741497E-01 -6.0...
   2.8637183010156E+08 +6.9259433874053E-01 +3.8202240378948E-01 -6.0...
</PRE>
<BR><BR>
<A NAME="Sampling Orientation of a Built-in Frame"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Sampling Orientation of a Built-in Frame
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to print the rotation from the
   ``J2000'' frame to the ``ECLIPJ2000'' frame, both of which are built-in
   frames. To get this rotation, ``J2000'' is specified using ``-f1'' and
   ``ECLIPJ2000'' is specified using ``-t1''. While it may seem that no
   kernels would be needed in this case, it is not true. An LSK must be
   provided to the program because the time at which the orientation should
   be computed must be provided on the command line twice using the ``-b''
   and ``-e'' keys and this time has to be converted to TDB inside the
   program. Therefore the program is given the LSK ``naif0009.tls'' using
   the ``-k'' option and an arbitrary time (``2000-01-01'') twice using the
   ``-b'' and ``-e'' options. The Euler angle dump report is picked using
   ``-t dump'' with the axis order X,Y,Z picked using ``-o x y z''. The
   angles are requested to be printed in degrees using ``-x degrees''.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls \
             -f1 J2000 -t1 ECLIPJ2000 \
             -b 2000-01-01 -e 2000-01-01 \
             -t dumpea -o x y z -x degrees
   #
   # Sampling of 1 rotations
   #
   #    from 'J2000' (1) to 'ECLIPJ2000' (17)
   #    computed using
   #
   #       naif0009.tls
   #
   # at continuous coverage intervals' endpoints
   # within the continuous time period
   #
   #    from '2000 JAN 01 00:01:04.183' TDB (-43135.816087188 TDB sec...
   #    to   '2000 JAN 01 00:01:04.183' TDB (-43135.816087188 TDB sec...
   #
   # Times are TDB seconds past J2000.
   #
   # angles are shown in degrees.
   #
   # time, ang3_about_X, ang2_about_Y, ang1_about_Z
   -4.3135816087188E+04 +2.3439291111111E+01 +0.0000000000000E+00 +0....
</PRE>
<BR><BR>
<A NAME="Sampling Orientation of a Dynamic Frame"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Sampling Orientation of a Dynamic Frame
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to sample orientation of the
   Geocentric Solar Ecliptic frame (``GSE''), a dynamic frame defined in
   the FK ``RSSD0002.TF'', relative to the ``J2000'' inertial frame and
   print this orientation as Euler angles tagged with Julian day TDB. The
   frames are specified using ``-f1'' and ``-t1''. All kernels needed to
   compute this transformation and convert times -- the FK, LSK
   ``NAIF0009.TLS'' and SPK ``DE405.BSP'' -- are listed using the ``-k''
   key. Since there are no primary kernels, the default coverage window
   cannot be picked automatically. Therefore the coverage window boundaries
   are specified using ``-b'' and ``-e''. The step is set to 1 day using
   ``-s 86400''. The Euler angles dump report is requested using ``-t
   dumpea''. The time format for output is set to be the Julian day TDB
   using
<P>
 
<PRE>
   -f 'JULIAND.######### ::TDB''
</PRE>
   The program's output is re-directed to the file ``output.txt'' using the
   ``&gt;'' shell pipe, with the contents of the file shown using the UNIX
   ``cat'' command.
<P>
 
<PRE>
   % frmdiff -k RSSD0002.TF NAIF0009.TLS DE405.BSP \
             -f1 J2000 -t1 GSE \
             -b 2008-01-01 -e 2009-01-01 -s 86400 \
             -t dumpea -f 'YYYY-MM-DD HR:MN:SC.### ::RND ::TDB' \
             &gt; output.txt
   % cat output.txt
   #
   # Sampling of 367 rotations
   #
   #    from 'J2000' (1) to 'GSE' (1500399)
   #    computed using
   #
   #       RSSD0002.TF ../lsk/NAIF0009.TLS ../spk/DE405.BSP
   #
   # with a 86400.000000000 second (1:00:00:00.000000) step size
   # within the continuous time period
   #
   #    from '2008 JAN 01 00:01:05.183' TDB (252417665.18391 TDB seco...
   #    to   '2009 JAN 01 00:01:06.183' TDB (284040066.18393 TDB seco...
   #
   # Times were generated by TIMOUT using 'JULIAND.######### ::TDB' f...
   #
   # angles are shown in radians.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   2454466.500754400 -1.3994266054604E+00 +1.6337747151270E-06 +4.090...
   2454467.500754400 -1.3816355414305E+00 +1.6343360047251E-06 +4.090...
   ...
   2454831.500754400 -1.4039978657128E+00 +1.8387392674578E-06 +4.090...
   2454832.500766000 -1.3862038203964E+00 +1.8393010792771E-06 +4.090...
</PRE>
<BR><BR>
<A NAME="Displaying Overlap in Coverage between Two CKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Displaying Overlap in Coverage between Two CKs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to determine the time intervals when
   both the MRO spacecraft CK ``mro_sc_psp_080408_080414.bc'' and MRO CRISM
   instrument CK ``mro_crm_psp_080413_080430.bc'' provide coverage and to
   display the boundaries of these intervals as UTC in ISO DOY format. The
   CKs are provided as the two primary kernels with other kernels -- the
   LSK ``naif0009.tls'' and the SCLK ``MRO_SCLKSCET.00027.65536.tsc'',
   required for time conversions, and the MRO FK ``mro_v13.tf'', defining
   frames used in the CKs, -- provided using ``-k''. The report is set to
   the coverage intervals dump using ``-t dumpc'' and the output time
   format is set to UTC in ISO DOY format using
<P>
 
<PRE>
   -f 'YYYY-DOYTHR:MN:SC.### ::RND'
</PRE>
   For runs like this usually both ``from'' frames and both ``to'' frames
   should be specified using ``-f1'', ``-f2'', ``-t1'', and ``-t2'' and
   these frames should match the base and structure frames from the CK
   files (the names of the base and structure frames can be seen in the CK
   summary produced by the ``BRIEF'' utility program run using the ``-rel
   -n'' options).
<P>
 
<PRE>
   % frmdiff -k naif0009.tls MRO_SCLKSCET.00027.65536.tsc mro_v13.tf \
             -f1 MRO_MME_OF_DATE -t1 MRO_SPACECRAFT \
             -f2 MRO_CRISM_BASE  -t2 MRO_CRISM_ART \
             -t dumpc -f 'YYYY-DOYTHR:MN:SC.### ::RND' \
             mro_sc_psp_080408_080414.bc mro_crm_psp_080413_080430.bc
   #
   # Coverage overlap for rotation
   #
   #    from 'MRO_MME_OF_DATE' (-74900) to 'MRO_SPACECRAFT' (-74000)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.65536.tsc mro_v13.tf
   #       mro_sc_psp_080408_080414.bc
   #
   # and rotation
   #
   #    from 'MRO_CRISM_BASE' (-74011) to 'MRO_CRISM_ART' (-74012)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.65536.tsc mro_v13.tf
   #       mro_crm_psp_080413_080430.bc
   #
   # with a 0.56599156324219 second (0:00:00:00.565992) step size
   # within the non-continuous (with 22 gaps) time period
   #
   #    from '2008 APR 13 00:29:16.745' TDB (261318556.74553 TDB seco...
   #    to   '2008 APR 13 01:12:03.742' TDB (261321123.74222 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-DOYTHR:MN:SC.### ::RN...
   #
   # interval_start, interval_stop, interval_duration_sec, interval_d...
   2008-104T00:28:11.560 2008-104T00:31:11.564         180.003858    ...
   2008-104T00:43:10.558 2008-104T00:43:14.559           4.001042    ...
   ...
   2008-104T01:10:08.423 2008-104T01:10:12.424           4.000950    ...
   2008-104T01:10:54.556 2008-104T01:10:58.557           4.001042    ...
</PRE>
<BR><BR>
<A NAME="Displaying Gaps in a CK File"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Displaying Gaps in a CK File
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In this example the program is run to display the gaps in the CASSINI CK
   ``09006_09011ra.bc''. The CK is given as the only primary kernel, with
   all other kernels -- the LSK ``naif0009.tls'' and the SCLK
   ``cas00130.tsc'', required for time conversions, and the CASSINI FK
   ``cas_v40.tf'', defining frames used in the CK, -- provided using
   ``-k''. The report type is set to the coverage gaps dump using ``-t
   dumpg'' and the output time format is set to UTC in ISO date format
   using
<P>
 
<PRE>
   -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
</PRE>
   There is no need to specify the ``to'' and ``from'' frames because the
   program will pick them automatically by examining the CK file.
<P>
 
<PRE>
   % frmdiff -k naif0009.tls cas00130.tsc cas_v40.tf \
             -t dumpg -f 'YYYY-MM-DDTHR:MN:SC.### ::RND' \
             09006_09011ra.bc
   #
   # Coverage for rotation
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09006_09011ra.bc
   #
   # with a 439.60863577834 second (0:00:07:19.608636) step size
   # within the non-continuous (with 8 gaps) time period
   #
   #    from '2009 JAN 06 00:01:08.565' TDB (284472068.56521 TDB seco...
   #    to   '2009 JAN 11 00:01:05.243' TDB (284904065.24341 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC.### ::...
   #
   # gap_start, gap_stop, gap_duration_sec, gap_duration_string
   2009-01-06T13:45:49.779 2009-01-06T13:46:10.029          20.249856...
   2009-01-06T15:15:49.740 2009-01-06T15:16:49.990          60.249572...
   ...
   2009-01-09T15:16:43.897 2009-01-09T15:17:12.147          28.249799...
   2009-01-10T17:18:27.481 2009-01-10T17:18:55.480          27.999801...
</PRE>
<BR><BR>
<A NAME="Miscellaneous Things to Consider"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Miscellaneous Things to Consider
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="``Apples vs. Oranges''"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> ``Apples vs. Oranges''
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Even though the program has the flexibility to compare any two
   transformations -- for example the transformation from the ``J2000''
   frame to the ``IAU_MARS'' frame with the transformation from the
   ``MRO_SPACECRAFT'' frame to the ``MRO_CTX'' frame -- it doesn't mean
   that such comparisons make sense. In general, it makes sense to compare
   only transformations that are close to each other and have the same
   ``from'' frame.
<P>
 
<BR><BR>
<A NAME="Using Euler Angles for Small Rotation Differences"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using Euler Angles for Small Rotation Differences
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   While Euler angles included in the Euler angles dump report (``-t
   dumpea'') may be one of the more intuitive representations of rotations,
   in many cases, depending on the rotation order, the angle magnitudes can
   be large and not representative of the small rotation differences. The
   total rotation angle provided in the rotation angle and axis report
   (``-t dumpaa'') is a much more reliable indicator of the difference of
   two rotations.
<P>
 
<BR><BR>
<A NAME="Single Epoch"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Single Epoch
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Due to the algorithm which the program uses to determine the coverage
   window, when orientations must be compared at, or an orientation must be
   sampled at, a certain epoch this epoch must be provided on the command
   line twice, once using the ``-b'' key and once using the ``-e'' key.
<P>
 
<BR><BR>
<A NAME="References"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> References
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<UL>
<TT>1.</TT> Frames Required Reading (<a href="../req/frames.html">frames.req</a>)
<BR><BR></UL>
<UL>
<TT>2.</TT> CK Required Reading (<a href="../req/ck.html">ck.req</a>)
<BR><BR></UL>
<UL>
<TT>3.</TT> PCK Required Reading (<a href="../req/pck.html">pck.req</a>)
<BR><BR></UL>
<UL>
<TT>4.</TT> ROTATIONS Required Reading (<a href="../req/rotation.html">rotation.req</a>)
<BR><BR></UL>
<UL>
<TT>5.</TT> TIME Required Reading (<a href="../req/time.html">time.req</a>)
<BR><BR></UL>
<UL>
<TT>6.</TT> SCLK Required Reading (<a href="../req/sclk.html">sclk.req</a>)
<BR><BR></UL>
<BR><BR>
<A NAME="Acronyms"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Acronyms
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<DL><DT>
<B>
 AV
</B><BR><BR>
<DD>
 angular velocity<BR>
</DL>
<DL><DT>
<B>
 ET
</B><BR><BR>
<DD>
 Ephemeris Time (synonymous to TDB)<BR>
</DL>
<DL><DT>
<B>
 SCLK
</B><BR><BR>
<DD>
 Spacecraft CLocK time<BR>
</DL>
<DL><DT>
<B>
 TDB
</B><BR><BR>
<DD>
 Barycentric Dynamical Time (synonymous to ET)<BR>
</DL>
<BR><BR>
<A NAME="Appendix 1: Comparison, Sampling and Report Quantity Algorithms"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix 1: Comparison, Sampling and Report Quantity Algorithms
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Computing Rotation and Angular Velocity Difference"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Computing Rotation and Angular Velocity Difference
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   When run in comparison mode the program uses the following SPICE
   routines to compute the rotation and angular velocity differences at
   each of the times:
<P>
 
<UL>
<TT>--</TT> if only rotations (without angular velocities) are to be compared:
<BR><BR></UL>
<PRE>
            <a href="../cspice/pxform_c.html">pxform_c</a> ( FROM1, TO1, ET, M1 );
            <a href="../cspice/pxform_c.html">pxform_c</a> ( FROM2, TO2, ET, M2 );
 
            <a href="../cspice/mxmt_c.html">mxmt_c</a>   ( M1, M2, MDIFF );
</PRE>
<UL>
<TT>--</TT> if rotations and angular velocities in the ``from'' frames are to be
compared:
<BR><BR></UL>
<PRE>
            <a href="../cspice/sxform_c.html">sxform_c</a> ( FROM1, TO1, ET, X1 );
            <a href="../cspice/xf2rav_c.html">xf2rav_c</a> ( X1, M1, AV1 );
 
            <a href="../cspice/sxform_c.html">sxform_c</a> ( FROM2, TO2, ET, X2 );
            <a href="../cspice/xf2rav_c.html">xf2rav_c</a> ( X2, M2, AV2 );
 
            <a href="../cspice/mxmt_c.html">mxmt_c</a>   ( M1, M2, MDIFF );
            <a href="../cspice/vsub_c.html">vsub_c</a>   ( AV1, AV2, AVDIFF );
</PRE>
<UL>
<TT>--</TT> if rotations and angular velocities in the ``to'' frames are to be
compared:
<BR><BR></UL>
<PRE>
            <a href="../cspice/sxform_c.html">sxform_c</a> ( FROM1, TO1, ET, X1 );
            <a href="../cspice/xf2rav_c.html">xf2rav_c</a> ( X1, M1, AV1 );
 
            <a href="../cspice/sxform_c.html">sxform_c</a> ( FROM2, TO2, ET, X2 );
            <a href="../cspice/xf2rav_c.html">xf2rav_c</a> ( X2, M2, AV2 );
 
            <a href="../cspice/mxmt_c.html">mxmt_c</a>   ( M1, M2, MDIFF );
            <a href="../cspice/vsub_c.html">vsub_c</a>   ( AV1, AV2, AVDIFFFR );
 
            <a href="../cspice/mxv_c.html">mxv_c</a>    ( M1, AVDIFFFR, AVDIFF );
</PRE>
   where FROM1, FROM2, TO1, TO2, and ET are the ``from'' and ``to'' frames
   of interest and time, MDIFF and AVDIFF are the rotation and angular
   velocity differences to be reported.
<P>
 
<BR><BR>
<A NAME="Sampling Rotation and Angular Velocity"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Sampling Rotation and Angular Velocity
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   When run in sampling mode the program uses the following SPICE routines
   to compute the rotation and angular velocity at each of the times:
<P>
 
<UL>
<TT>--</TT> if only rotation (without angular) velocity is to be sampled:
<BR><BR></UL>
<PRE>
            <a href="../cspice/pxform_c.html">pxform_c</a> ( FROM, TO, ET, MDIFF );
</PRE>
<UL>
<TT>--</TT> if rotation and angular velocity in the ``from'' frame is to be sampled:
<BR><BR></UL>
<PRE>
            <a href="../cspice/sxform_c.html">sxform_c</a> ( FROM, TO, ET, X );
            <a href="../cspice/xf2rav_c.html">xf2rav_c</a> ( X, MDIFF, AVDIFF );
</PRE>
<UL>
<TT>--</TT> if rotation and angular velocity in the ``to'' frame is to be sampled:
<BR><BR></UL>
<PRE>
            <a href="../cspice/sxform_c.html">sxform_c</a> ( FROM, TO, ET, X );
            <a href="../cspice/xf2rav_c.html">xf2rav_c</a> ( X, MDIFF, AV );
 
            <a href="../cspice/mxv_c.html">mxv_c</a>    ( MDIFF, AV, AVDIFF );
</PRE>
   where FROM, TO, and ET are the ``from'' and ``to'' frames of interest
   and time, MDIFF and AVDIFF are the rotation and angular velocity to be
   reported.
<P>
 
<BR><BR>
<A NAME="Converting Rotation to Angle/Axis"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Converting Rotation to Angle/Axis
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   If no ``-t'' is specified, or if ``-t basic'', ``-t stats'', or ``-t
   dumpaa'' is specified, the program converts MDIFF to the rotation angle
   and axis using
<P>
 
<PRE>
            <a href="../cspice/raxisa_c.html">raxisa_c</a> ( MDIFF, AXIS, ANGLE );
</PRE>
<BR><BR>
<A NAME="Converting Rotation to SPICE-Style Quaternion"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Converting Rotation to SPICE-Style Quaternion
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   If ``-t dumpqs'' is specified, the program converts MDIFF to the
   SPICE-style quaternion using
<P>
 
<PRE>
            <a href="../cspice/m2q_c.html">m2q_c</a> ( MDIFF, QS );
</PRE>
<BR><BR>
<A NAME="Converting Rotation to ``Other''-Style quaternion"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Converting Rotation to ``Other''-Style quaternion
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   If ``-t dumpqo'' is specified, the program converts MDIFF to the
   ``other''-style quaternion using
<P>
 
<PRE>
            <a href="../cspice/m2q_c.html">m2q_c</a> ( MDIFF, QS );
            QO[0] = -QS[1];
            QO[1] = -QS[2];
            QO[2] = -QS[3];
            QO[3] =  QS[0];
</PRE>
<BR><BR>
<A NAME="Converting Rotation to Euler Angles"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Converting Rotation to Euler Angles
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   If ``-t'' dumpea is specified, the program converts MDIFF to Euler
   angles using
<P>
 
<PRE>
            <a href="../cspice/m2eul_c.html">m2eul_c</a> ( MDIFF, AXIS3, AXIS2, AXIS1, ANG3, ANG2, ANG1 );
</PRE>
   where AXIS1-3 are either defaults (``Z Y X'') or the axes specified
   using the ``-o'' key. The axes are ``passed'' as input to M2EUL in the
   same order as they are listed using ``-o''. For example, for ``-o X Z
   Y'' M2EUL is called with ``( MDIFF, 1, 3, 2, ...)''.
<P>
 

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
